stipa 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80e062eee66bb5fb015d00f45bb604c85ad905fbf35bbb32652ac48dbbc2b888
-  data.tar.gz: c2883dd7c9e9bf9025330d43ee0053bfb602841c47c12683df67497fe41a59f7
+  metadata.gz: abdc053626744d0381f7335db140ba8db53b10417709d497a42576bba6b7b9cd
+  data.tar.gz: 7baaa2ff8bf626791f07c21984a554cfe313a25755ef4ee4ef8c18f48bef27ec
 SHA512:
-  metadata.gz: 2c434487c1186267976b98d73e3dfa9723babd352f46eacadaf0623045668e99e02972c12799c5123f11e35cc8855253ade8de05d6e913e958fde156138b67c2
-  data.tar.gz: feca4e22d0712c1fd927a828c49bed7e6696575fdb34cef8c2a73e013e50a2c7523c44a2a35c1a9ba12d416a1fe4cd4cf35b395b8d8ff5f77e1002ddb5c07359
+  metadata.gz: 8b149710bae024245ef518ce3e9c199ef3eccb3271423e6eee17b03b3e655ae017208bc5db412e31a460c08a1072ec8aac4c46cae3381952abf7929e120d9fb4
+  data.tar.gz: 2ec4167d53cd1ad5d099c1d4e458c439ade9c69bab612604e2002931eef7c7010872b6f37bc0e544f46247e76476f65b6c0f9cabea5beba856a6dcd36934aa87

data/README.md

@@ -15,6 +15,7 @@
 - **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
+- **Database layer** — optional Sequel integration with migrations, models, and connection management
 
 ---
 
@@ -73,15 +74,21 @@ Generated structure (`--vue`):
 myapp/
 ├── server.rb                    # entry point
 ├── Gemfile
+├── Rakefile                     # db:migrate, db:rollback, db:version
 ├── package.json                 # rollup + vue + typescript
 ├── rollup.config.js
 ├── tsconfig.json
-├── src/
-│   ├── config/routes.rb
+├── app/
+│   ├── config/
+│   │   ├── database.rb          # DATABASE_URL, Sequel settings
+│   │   └── routes.rb
 │   ├── controllers/
 │   ├── models/
+│   │   └── application_model.rb # base model with Stipa::Model
 │   ├── views/
 │   └── components/              # Vue SFC source (.vue, .ts)
+├── db/
+│   └── migrate/                 # Sequel migrations
 └── public/
     ├── stipa-vue.js
     ├── app.css
@@ -324,6 +331,116 @@ Handles `SIGTERM` / `SIGINT` with graceful drain.
 
 ---
 
+## Database
+
+Optional Sequel integration. Add to your Gemfile:
+
+```ruby
+gem 'sequel'
+gem 'pg'          # or mysql2, sqlite3
+```
+
+Configure via `DATABASE_URL`:
+
+```bash
+# .env (development / test)
+DATABASE_URL=postgres://user:password@localhost:5432/myapp
+```
+
+```ruby
+require 'stipa/database'
+
+Stipa::Database.connect!
+DB = Stipa::Database.connection
+
+# health check
+Stipa::Database.healthy?  # => true
+
+# transactions
+Stipa::Database.transaction { DB[:posts].insert(title: 'Hello') }
+
+# shutdown
+Stipa::Database.disconnect!
+```
+
+### Migrations
+
+```bash
+rake db:migrate    # run pending migrations
+rake db:rollback   # rollback last migration
+rake db:version    # show current version
+```
+
+Create a migration:
+
+```ruby
+# db/migrate/002_create_comments.rb
+Sequel.migration do
+  change do
+    create_table :comments do
+      primary_key :id
+      foreign_key :post_id, null: false
+      String :body, text: true
+      DateTime :created_at, null: false
+      DateTime :updated_at, null: false
+    end
+  end
+end
+```
+
+---
+
+## Models
+
+Models use `Stipa::Model` — a set of Sequel plugins for common patterns:
+
+```ruby
+require 'stipa/model'
+
+class Post < ApplicationModel
+  # Included by default:
+  #   - Timestamps    (created_at / updated_at)
+  #   - UUID          (auto-generate UUID primary key)
+  #   - SoftDelete    (deleted_at scoping)
+  #   - Serialization (to_hash, to_json, from_json)
+
+  plugin :validation_helpers
+
+  def validate
+    super
+    validates_presence [:title]
+    validates_unique   [:slug]
+  end
+end
+```
+
+### Standalone modules
+
+Use individual modules without the full `Stipa::Model` bundle:
+
+```ruby
+class User < Sequel::Model
+  include Stipa::Model::UUID
+  include Stipa::Model::Pagination
+end
+
+# Pagination
+result = User.paginate(page: 2, per_page: 10)
+result[:records]     # => [#<User>, ...]
+result[:total]       # => 150
+result[:total_pages] # => 15
+
+# Soft delete
+user.soft_delete
+user.deleted?       # => true
+User.all            # => excludes soft-deleted
+User.with_deleted   # => includes all
+User.only_deleted   # => soft-deleted only
+user.restore
+```
+
+---
+
 ## License
 
 MIT

data/lib/stipa/app.rb

@@ -1,9 +1,9 @@
 require_relative 'version'
 require_relative 'logger'
-require_relative 'server'
-require_relative 'middleware'
-require_relative 'request'
-require_relative 'response'
+require_relative 'server/server'
+require_relative 'middleware/stack'
+require_relative 'http/request'
+require_relative 'http/response'
 
 module Stipa
   # User-facing DSL for defining routes and middleware.

data/lib/stipa/database.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'sequel'
+
+module Stipa
+  # Database connection manager.
+  #
+  # Usage:
+  #   require 'stipa/database'
+  #
+  #   Stipa::Database.connect!  # reads DATABASE_URL from environment
+  #   DB = Stipa::Database.connection
+  #
+  # Environment variables:
+  #   DATABASE_URL      — connection string (required)
+  #   DATABASE_POOL     — max connections (default: 5)
+  #
+  # Connection string examples:
+  #   postgres://user:pass@localhost:5432/myapp
+  #   mysql2://user:pass@localhost:3306/myapp
+  #   sqlite://db/development.db
+  #
+  module Database
+    module_function
+
+    def connect!
+      return @connection if @connection
+
+      @connection = Sequel.connect(
+        ENV.fetch('DATABASE_URL'),
+        max_connections: Integer(ENV.fetch('DATABASE_POOL', '5')),
+        connect_timeout: 5,
+        test: true,
+        keep_reference: false,
+        after_connect: lambda do |connection|
+          connection.exec("SET TIME ZONE 'UTC'") if connection.respond_to?(:exec)
+        end
+      )
+
+      configure_connection!
+      @connection
+    rescue KeyError => e
+      raise "Missing database configuration: #{e.message}"
+    rescue ArgumentError => e
+      raise "Invalid database configuration: #{e.message}"
+    end
+
+    def connection
+      @connection || raise('Database.connect! must be called first')
+    end
+
+    def connected?
+      !@connection.nil?
+    end
+
+    def healthy?
+      connection.get(Sequel.lit('SELECT 1')) == 1
+    rescue Sequel::Error
+      false
+    end
+
+    def disconnect!
+      @connection&.disconnect
+      @connection = nil
+    end
+
+    def transaction(&block)
+      connection.transaction(&block)
+    end
+
+    # -------------------------------------------------------------------
+    # Database-specific extensions
+    # -------------------------------------------------------------------
+    #
+    # The defaults below are tuned for PostgreSQL. If you're using a
+    # different adapter, comment out or remove the lines that don't apply.
+    #
+    # ── PostgreSQL ──────────────────────────────────────────────────────
+    # No changes needed — the lines below work out of the box.
+    #
+    # ── MySQL / MariaDB ─────────────────────────────────────────────────
+    # Replace the body of this method with:
+    #
+    #   def configure_connection!
+    #     return unless @connection.adapter_scheme == :mysql
+    #
+    #     @connection.extension :pg_json      # not available — remove
+    #     @connection.extension :pg_array     # not available — remove
+    #
+    #     Sequel.extension :pg_json_ops       # not available — remove
+    #     Sequel.extension :pg_array_ops      # not available — remove
+    #   end
+    #
+    # ── SQLite ──────────────────────────────────────────────────────────
+    # Replace the body of this method with:
+    #
+    #   def configure_connection!
+    #     return unless @connection.adapter_scheme == :sqlite
+    #
+    #     @connection.extension :pagination   # optional: simple pagination
+    #   end
+    #
+    # ── Generic / adapter-agnostic ──────────────────────────────────────
+    # If you want a safe default that works with any adapter:
+    #
+    #   def configure_connection!
+    #     # No adapter-specific extensions.
+    #     # Add extensions conditionally based on adapter_scheme:
+    #     #
+    #     # case @connection.adapter_scheme
+    #     # when :postgres
+    #     #   @connection.extension :pg_json
+    #     #   @connection.extension :pg_array
+    #     # when :sqlite
+    #     #   @connection.extension :pagination
+    #     # end
+    #   end
+    #
+    def configure_connection!
+      return unless @connection.adapter_scheme == :postgres
+
+      @connection.extension :pg_json
+      @connection.extension :pg_array
+
+      Sequel.extension :pg_json_ops
+      Sequel.extension :pg_array_ops
+    end
+
+    private_class_method :configure_connection!
+  end
+end

data/lib/stipa/generators/api.rb

@@ -8,7 +8,7 @@ module Stipa
       def template_name = 'api'
 
       def dirs
-        %w[config controllers]
+        %w[config controllers models db/migrate]
       end
 
       def done_message
@@ -25,13 +25,17 @@ module Stipa
         {
           '.gitignore'                             => t_gitignore,
           'Gemfile'                                => t_gemfile,
+          'Rakefile'                               => t_rakefile,
           'server.rb'                              => t_server,
+          'config/database.rb'                     => t_database_config,
           'config/routes.rb'                       => t_routes(
             extra_requires: ['../controllers/health_controller'],
             extra_routes:   ["get '/health', to: 'health#show'"],
           ),
           'controllers/application_controller.rb' => t_application_controller,
           'controllers/health_controller.rb'       => t_health_controller,
+          'models/application_model.rb'            => t_application_model,
+          'db/migrate/001_create_posts.rb'         => t_migration_create_posts,
         }
       end
 
@@ -42,8 +46,16 @@ module Stipa
       def t_server
         <<~RUBY
           require 'stipa'
+          require 'stipa/database'
+
+          require_relative 'config/database'
           require_relative 'config/routes'
 
+          Stipa::Database.connect!
+
+          # Models must be loaded after the database connection is established.
+          require_relative 'models/application_model'
+
           app = Stipa::App.new
 
           app.use Stipa::Middleware::RequestId
@@ -52,6 +64,14 @@ module Stipa
 
           Routes.draw(app)
 
+          app.get '/api/health' do |_req, res|
+            res.json({ status: 'ok', framework: 'Stipa', version: Stipa::VERSION, ts: Time.now.utc.iso8601 })
+          end
+
+          at_exit do
+            Stipa::Database.disconnect!
+          end
+
           app.start(host: '127.0.0.1', port: 3710)
         RUBY
       end

data/lib/stipa/generators/base.rb

@@ -87,6 +87,13 @@ module Stipa
           source 'https://rubygems.org'
 
           gem 'stipa'
+          gem 'sequel'
+          gem 'dotenv'
+
+          # Database adapter — uncomment the one you need:
+          # gem 'pg'          # PostgreSQL
+          # gem 'mysql2'      # MySQL / MariaDB
+          # gem 'sqlite3'     # SQLite
         RUBY
       end
 
@@ -148,6 +155,116 @@ module Stipa
           end
         RUBY
       end
+
+      def t_database_config
+        <<~RUBY
+          # frozen_string_literal: true
+
+          environment = ENV.fetch('APP_ENV', 'development')
+
+          case environment
+          when 'development', 'test'
+            require 'dotenv/load'
+          end
+
+          # Set DATABASE_URL in your .env file (development/test) or environment (production).
+          #
+          # PostgreSQL:
+          #   DATABASE_URL=postgres://user:password@localhost:5432/myapp
+          #
+          # MySQL:
+          #   DATABASE_URL=mysql2://user:password@localhost:3306/myapp
+          #
+          # SQLite:
+          #   DATABASE_URL=sqlite://db/development.db
+
+          Sequel.database_timezone = :utc
+          Sequel.application_timezone = :local
+        RUBY
+      end
+
+      def t_application_model
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require 'stipa/model'
+
+          class ApplicationModel < Sequel::Model
+            include Stipa::Model
+
+            def self.dataset
+              super
+            rescue Sequel::Error => e
+              raise "Database not ready: \#{e.message}"
+            end
+          end
+        RUBY
+      end
+
+      def t_migration_create_posts
+        <<~RUBY
+          # frozen_string_literal: true
+
+          Sequel.migration do
+            change do
+              create_table :posts do
+                primary_key :id
+                String  :title,       null: false
+                String  :body,        text: true
+                String  :slug,        null: false
+                DateTime :created_at, null: false
+                DateTime :updated_at, null: false
+
+                index :slug, unique: true
+              end
+            end
+          end
+        RUBY
+      end
+
+      def t_rakefile
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require 'rake'
+          require 'stipa/database'
+
+          namespace :db do
+            desc 'Run pending migrations'
+            task :migrate do
+              load_config
+              Sequel::Migrator.run(Stipa::Database.connection, 'db/migrate')
+              puts "Migrated to \#{Stipa::Database.connection[:schema_info].first[:version]}"
+            end
+
+            desc 'Rollback the last migration'
+            task :rollback do
+              load_config
+              Sequel::Migrator.run(Stipa::Database.connection, 'db/migrate', target: current_version - 1)
+              puts "Rolled back to \#{current_version}"
+            end
+
+            desc 'Show current migration version'
+            task :version do
+              load_config
+              puts "Current version: \#{current_version}"
+            end
+          end
+
+          task default: 'db:migrate'
+
+          def load_config
+            require_relative 'config/database'
+            Stipa::Database.connect!
+          end
+
+          def current_version
+            Stipa::Database.connection[:schema_info].first[:version]
+          rescue
+            0
+          end
+        RUBY
+      end
     end
   end
 end

data/lib/stipa/generators/vue.rb

@@ -15,6 +15,7 @@ module Stipa
           app/views/layouts
           app/views/home
           app/components
+          db/migrate
           public/vendor
         ]
       end
@@ -55,10 +56,12 @@ module Stipa
         {
           '.gitignore'                             => t_gitignore,
           'Gemfile'                                => t_gemfile,
+          'Rakefile'                               => t_rakefile,
           'package.json'                           => t_package_json,
           'rollup.config.js'                       => t_rollup_config,
           'tsconfig.json'                          => t_tsconfig,
           'server.rb'                                      => t_server,
+          'app/config/database.rb'                        => t_database_config,
           'app/config/routes.rb'                         => t_routes(
             extra_requires: ['../controllers/home_controller', '../controllers/health_controller'],
             extra_routes:   ["get '/', to: 'home#index'", "get '/api/health', to: 'health#show'"],
@@ -67,6 +70,8 @@ module Stipa
           'app/controllers/application_controller.rb'   => t_application_controller,
           'app/controllers/home_controller.rb'           => t_home_controller,
           'app/controllers/health_controller.rb'         => t_health_controller,
+          'app/models/application_model.rb'              => t_application_model,
+          'db/migrate/001_create_posts.rb'               => t_migration_create_posts,
           'app/views/layouts/application.html.erb'      => t_layout,
           'app/views/home/index.html.erb'                => t_home_index,
           'public/app.css'                               => t_app_css,
@@ -151,8 +156,16 @@ module Stipa
       def t_server
         <<~RUBY
           require 'stipa'
+          require 'stipa/database'
+
+          require_relative 'app/config/database'
           require_relative 'app/config/routes'
 
+          Stipa::Database.connect!
+
+          # Models must be loaded after the database connection is established.
+          require_relative 'app/models/application_model'
+
           APP_DIR = __dir__
 
           app = Stipa::App.new(
@@ -169,6 +182,10 @@ module Stipa
             res.json({ status: 'ok', framework: 'Stipa', version: Stipa::VERSION, ts: Time.now.utc.iso8601 })
           end
 
+          at_exit do
+            Stipa::Database.disconnect!
+          end
+
           app.start(host: '127.0.0.1', port: 3710)
         RUBY
       end

data/lib/stipa/{connection.rb → http/connection.rb}

@@ -1,4 +1,6 @@
 require 'socket'
+require_relative 'request'
+require_relative 'response'
 
 module Stipa
   # Manages the HTTP/1.1 keep-alive request/response loop for a single socket.

data/lib/stipa/model/pagination.rb

@@ -0,0 +1,28 @@
+module Stipa
+  module Model
+    module Pagination
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def paginate(page: 1, per_page: 20)
+          page  = [page.to_i, 1].max
+          per_page = [per_page.to_i, 1].max
+
+          total   = count
+          records = limit(per_page).offset((page - 1) * per_page).all
+          total_pages = (total.to_f / per_page).ceil
+
+          {
+            records:      records,
+            page:         page,
+            per_page:     per_page,
+            total:        total,
+            total_pages:  total_pages,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/stipa/model/serialization.rb

@@ -0,0 +1,25 @@
+require 'json'
+
+module Stipa
+  module Model
+    module Serialization
+      def to_hash
+        columns.each_with_object({}) do |col, h|
+          h[col] = send(col)
+        end
+      end
+
+      def to_json(*args)
+        to_hash.to_json(*args)
+      end
+
+      def self.included(base)
+        base.instance_eval do
+          def from_json(json)
+            new(JSON.parse(json))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stipa/model/soft_delete.rb

@@ -0,0 +1,35 @@
+module Stipa
+  module Model
+    module SoftDelete
+      def self.included(base)
+        base.instance_eval do
+          dataset_module do
+            def deleted
+              where(deleted_at: !nil)
+            end
+
+            def not_deleted
+              where(deleted_at: nil)
+            end
+          end
+
+          def self.dataset
+            super.not_deleted
+          end
+        end
+      end
+
+      def soft_delete
+        update(deleted_at: Time.now.utc)
+      end
+
+      def restore
+        update(deleted_at: nil)
+      end
+
+      def deleted?
+        !deleted_at.nil?
+      end
+    end
+  end
+end

data/lib/stipa/model/timestamps.rb

@@ -0,0 +1,14 @@
+module Stipa
+  module Model
+    module Timestamps
+      def self.included(base)
+        base.instance_eval do
+          plugin :timestamps,
+                 create: :created_at,
+                 update: :updated_at,
+                 update_on_create: true
+        end
+      end
+    end
+  end
+end

data/lib/stipa/model/uuid.rb

@@ -0,0 +1,17 @@
+require 'securerandom'
+
+module Stipa
+  module Model
+    module UUID
+      def self.included(base)
+        base.instance_eval do
+          before_create { self.id ||= SecureRandom.uuid }
+        end
+      end
+
+      def to_param
+        id
+      end
+    end
+  end
+end

data/lib/stipa/model.rb

@@ -0,0 +1,19 @@
+require_relative 'model/uuid'
+require_relative 'model/soft_delete'
+require_relative 'model/serialization'
+require_relative 'model/timestamps'
+require_relative 'model/pagination'
+
+module Stipa
+  module Model
+    def self.included(base)
+      base.plugin :validation_helpers
+      base.plugin :dirty
+
+      base.include Timestamps
+      base.include UUID
+      base.include SoftDelete
+      base.include Serialization
+    end
+  end
+end

data/lib/stipa/{server.rb → server/server.rb}

@@ -1,9 +1,9 @@
 require 'socket'
 require_relative 'thread_pool'
-require_relative 'connection'
-require_relative 'request'
-require_relative 'response'
-require_relative 'logger'
+require_relative '../http/connection'
+require_relative '../http/request'
+require_relative '../http/response'
+require_relative '../logger'
 
 module Stipa
   # TCP accept loop and connection lifecycle manager.

data/lib/stipa/version.rb

@@ -1,3 +1,3 @@
 module Stipa
-  VERSION = '0.1.7'
+  VERSION = '0.2.0'
 end

data/lib/stipa.rb

@@ -5,27 +5,28 @@
 # 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
+#   version                    — no deps
+#   logger                     — no deps
+#   server/thread_pool         — no deps
+#   server/reloader            — no deps
+#   middleware/stack            — no deps
+#   middleware/static           — depends on middleware/stack
+#   template/template           — no deps (stdlib only: erb, json)
+#   http/request                — no deps
+#   http/response               — depends on template (via render helper)
+#   http/connection             — depends on http/request, http/response
+#   server/server               — depends on server/thread_pool, http/connection
+#   app                         — depends on server/server, middleware, template, http/request, http/response
 
 require_relative 'stipa/version'
 require_relative 'stipa/logger'
-require_relative 'stipa/thread_pool'
-require_relative 'stipa/reloader'
-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/server/thread_pool'
+require_relative 'stipa/server/reloader'
+require_relative 'stipa/middleware/stack'
+require_relative 'stipa/middleware/static'
+require_relative 'stipa/template/template'
+require_relative 'stipa/http/request'
+require_relative 'stipa/http/response'
+require_relative 'stipa/http/connection'
+require_relative 'stipa/server/server'
 require_relative 'stipa/app'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stipa
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - Jānis Harbs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -93,20 +93,27 @@ files:
 - lib/stipa.rb
 - lib/stipa/app.rb
 - lib/stipa/cli.rb
-- lib/stipa/connection.rb
+- lib/stipa/database.rb
 - lib/stipa/generator.rb
 - lib/stipa/generators/api.rb
 - lib/stipa/generators/base.rb
 - lib/stipa/generators/vue.rb
+- lib/stipa/http/connection.rb
+- lib/stipa/http/request.rb
+- lib/stipa/http/response.rb
 - lib/stipa/logger.rb
-- lib/stipa/middleware.rb
-- lib/stipa/reloader.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/middleware/stack.rb
+- lib/stipa/middleware/static.rb
+- lib/stipa/model.rb
+- lib/stipa/model/pagination.rb
+- lib/stipa/model/serialization.rb
+- lib/stipa/model/soft_delete.rb
+- lib/stipa/model/timestamps.rb
+- lib/stipa/model/uuid.rb
+- lib/stipa/server/reloader.rb
+- lib/stipa/server/server.rb
+- lib/stipa/server/thread_pool.rb
+- lib/stipa/template/template.rb
 - lib/stipa/version.rb
 - media/favicon.ico
 - media/logo.png