serrano-vk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 588a6ba96d25153b2afd982b7776df82258c0dc55c815db4e7c5215d8bbe6269
+  data.tar.gz: 80a56253e100646aea7291728b7fa3306e6c6e231502198f35bb465c6855ca79
+SHA512:
+  metadata.gz: 4dcbd11db6b2b6a5d37b888c1d197320d388242bb585e1048fbf071f6dd06674596b3d5d5894792fcc9dd5a76b1d280140f5cffb09769dab90a262c03829b937
+  data.tar.gz: 1806376a8178418d87ececdf9430ad64257d71a43f244ee477236d2e8c2127bdd0534af46bfd5a23aa2b8f117e068e0d394fdc16d5964d9a96294518a099bc25

data/EXAMPLES.md

@@ -0,0 +1,271 @@
+# Serrano - Full Examples
+
+This document is the usage cookbook for the framework and CLI.
+
+## 1) Core Runtime: Minimal HTTP App
+
+### 1.1 files
+
+`config.ru`:
+
+```ruby
+# frozen_string_literal: true
+
+require "serrano"
+
+class UsersController
+  def index(_request)
+    { users: [] }
+  end
+
+  def show(request)
+    { id: request.params['id'], via_query: request.params['foo'] }
+  end
+end
+
+app = Serrano::Application.new
+app.get "/users", UsersController, :index
+app.get "/users/:id", UsersController, :show
+
+run app
+```
+
+### 1.2 start and test
+
+```bash
+bundle exec rackup
+curl -i http://localhost:9292/users
+curl -i http://localhost:9292/users/12?foo=abc
+```
+
+Expected:
+- `GET /users` => `200 application/json`
+- `GET /users/12?foo=abc` => `200 application/json` and body contains `{"id":"12","via_query":"abc"}`
+
+---
+
+## 2) Return Contract
+
+### 2.1 Hash response
+
+```ruby
+def index(_request)
+  { ok: true, count: 10 }
+end
+```
+
+### 2.2 String response
+
+```ruby
+def ping(_request)
+  "pong"
+end
+```
+
+### 2.3 Custom response object
+
+```ruby
+def create(_request)
+  Serrano::Response.new(
+    status: 201,
+    headers: { "content-type" => "application/json" },
+    body: '{"created":true}'
+  )
+end
+```
+
+### 2.4 Error handling
+
+```ruby
+def crash(_request)
+  raise 'boom'
+end
+```
+
+- status `500`
+- body `{"error":"Internal Server Error"}`
+
+---
+
+## 3) Routing behaviors
+
+### 3.1 Static vs dynamic precedence
+
+```ruby
+app.get "/users/new", UsersController, :new
+app.get "/users/:id", UsersController, :show
+```
+
+`GET /users/new` must resolve to `:new` route.
+
+### 3.2 Multiple dynamic params
+
+```ruby
+app.get "/users/:user_id/posts/:post_id", PostsController, :show
+```
+
+### 3.3 405 when method exists for another verb
+
+If only `GET /users/:id` exists and you request `POST /users/1`:
+
+- `405`
+- body `{"error":"Method Not Allowed"}`
+- header `allow` containing only allowed methods
+
+---
+
+## 4) Request Object Helpers
+
+```ruby
+# In controller action
+request.path
+request.method
+request.params
+request.headers
+request.body
+request['id']
+```
+
+`request['id']` is sugar for `request.params['id']`.
+
+---
+
+## 5) CLI: bootstrap new projects
+
+## 5.1 create full project (recommended)
+
+```bash
+bundle exec ruby bin/serrano new my_app
+```
+
+Generated structure includes `app/`, `config.ru`, `Gemfile`, `config/db.rb`, `db/migrations/`.
+
+## 5.2 create full project + sqlite db
+
+```bash
+bundle exec ruby bin/serrano new my_app --db=sqlite
+```
+
+Adds sqlite dependency and DB config.
+
+## 5.3 minimal project
+
+```bash
+bundle exec ruby bin/serrano new my_app --minimal
+```
+
+Only boot files, no app/db scaffolding.
+
+## 5.4 minimal + db
+
+```bash
+bundle exec ruby bin/serrano new my_app --minimal --db=postgres
+```
+
+Orthogonal behavior: `--minimal` does not disable DB files.
+
+Next steps after `new`:
+
+```bash
+cd my_app
+bundle install
+bundle exec rackup
+```
+
+---
+
+## 6) CLI generate commands
+
+### 6.1 scaffold full resource
+
+```bash
+bundle exec ruby bin/serrano generate resource Article title:string content:text required:required
+```
+
+Creates:
+
+- `app/controllers/articles_controller.rb`
+- `app/services/articles/{index,show,create,update,destroy}.rb`
+- `app/repositories/article_repository.rb`
+- `app/entities/article.rb`
+- `db/migrations/*_create_articles.rb`
+- route suggestions printed in terminal (print-only)
+
+### 6.2 generate individual files
+
+```bash
+bundle exec ruby bin/serrano generate controller Comments
+bundle exec ruby bin/serrano generate service Reports::Monthly
+bundle exec ruby bin/serrano generate repository Comment
+```
+
+---
+
+## 7) Full CRUD example flow with articles resource
+
+This example assumes you are inside an app where `generate resource` already created files.
+
+### 7.1 Start server
+
+```bash
+bundle exec rackup
+```
+
+### 7.2 routes examples
+
+```bash
+curl -i http://localhost:9292/articles
+curl -i http://localhost:9292/articles/1
+curl -i -X POST http://localhost:9292/articles \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-raw "title=First&content=Hello"
+curl -i -X PUT http://localhost:9292/articles/1 \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-raw "title=Updated&content=Changed"
+curl -i -X DELETE http://localhost:9292/articles/1
+```
+
+Expected mapping:
+
+- `GET /articles` -> `index`
+- `GET /articles/:id` -> `show`
+- `POST /articles` -> `create`
+- `PUT /articles/:id` -> `update`
+- `DELETE /articles/:id` -> `destroy`
+
+---
+
+## 8) Error demos to reproduce and validate
+
+### 8.1 404
+
+```bash
+curl -i http://localhost:9292/does-not-exist
+```
+
+Expect `404` JSON `{"error":"Not Found"}`.
+
+### 8.2 405
+
+If route only has `GET`, call with `POST`/`PUT`/`DELETE` to same path and confirm `405` + `allow`.
+
+### 8.3 500
+
+Use a crashing action in controller:
+
+```ruby
+def crash(_request)
+  raise StandardError, 'boom'
+end
+```
+
+Expect:
+
+- `500`
+- body `{"error":"Internal Server Error"}`
+
+---
+
+## 9) Note on `config.ru` in generated resources
+
+The CLI keeps route insertion explicit and deterministic. If you scaffold in an empty `config.ru`, check and adjust routes manually when needed, especially if you want custom middleware or custom boot flow.

data/README.md

@@ -0,0 +1,170 @@
+# Serrano
+
+Serrano is a minimal Rack-based Ruby microframework with an explicit HTTP contract and no hidden behavior.
+
+---
+
+## What is Serrano
+
+Serrano provides only the HTTP runtime:
+
+- route registration and matching (`GET`, `POST`, `PUT`, `DELETE`)
+- controller dispatching
+- request and response wrappers
+- strict error-to-response mapping
+
+Serrano is intentionally small. It does not include:
+
+- an ORM
+- middleware stacks
+- dependency injection containers
+- architecture conventions beyond thin controller/service/repository layering
+
+If you want database or CRUD tooling, use the optional CLI and example scaffolding layer.
+
+---
+
+## Core Contracts
+
+- Supported methods: `GET`, `POST`, `PUT`, `DELETE`
+- Route DSL:
+  - `get(path, controller, action)`
+  - `post(path, controller, action)`
+  - `put(path, controller, action)`
+  - `delete(path, controller, action)`
+- Controller return values:
+  - `Hash` => JSON response, status `200`
+  - `String` => `text/plain`, status `200`
+  - `Serrano::Response` => use as-is
+  - other values => `500` with `Internal Server Error`
+- Missing route => `404 Not Found`
+- Missing method for existing path => `405 Method Not Allowed` with lowercase `allow` header and supported methods
+
+See [EXAMPLES.md](./EXAMPLES.md) for full request/response demos.
+
+---
+
+## Installation (local development)
+
+- Ruby `>= 3.2`
+- Add to your app Gemfile:
+
+```ruby
+# Gemfile
+ruby '3.4.0'
+
+gem 'serrano', path: '../serrano'
+```
+
+Run:
+
+```bash
+bundle install
+```
+
+---
+
+## Quick Start (Core only)
+
+`config.ru`:
+
+```ruby
+# frozen_string_literal: true
+
+require 'serrano'
+
+class UsersController
+  def index(_request)
+    { users: [] }
+  end
+end
+
+app = Serrano::Application.new
+app.get('/users', UsersController, :index)
+
+run app
+```
+
+Run:
+
+```bash
+bundle exec rackup
+```
+
+Quick check:
+
+```bash
+curl -i http://localhost:9292/users
+```
+
+---
+
+## Productivity Layer (CLI)
+
+The CLI is optional and depends on the core runtime.
+
+### Available commands
+
+```bash
+bundle exec ruby bin/serrano new APP_NAME [--minimal] [--db=sqlite|postgres|mysql]
+bundle exec ruby bin/serrano generate resource Article title:string content:text
+bundle exec ruby bin/serrano generate controller Name
+bundle exec ruby bin/serrano generate service Namespace::Name
+bundle exec ruby bin/serrano generate repository Name
+```
+
+- `new` creates project files (minimal mode and DB options are orthogonal)
+- `generate resource` creates controller, services (`index`, `show`, `create`, `update`, `destroy`), repository, entity, migration
+- route code is suggested in terminal output; automatic `config.ru` route editing is handled by generator logic when app file exists
+
+For full command usage with sample outputs and full flows, read [EXAMPLES.md](./EXAMPLES.md).
+
+---
+
+## Project Structure
+
+Core runtime:
+
+```text
+lib/serrano/
+  application.rb
+  cli/
+  dispatcher.rb
+  request.rb
+  response.rb
+  router.rb
+```
+
+Example app (optional):
+
+```text
+app/
+  controllers/
+  services/
+  repositories/
+  entities/
+config/
+  db.rb
+config.ru
+```
+
+---
+
+## Testing
+
+Core tests are isolated under:
+
+- `test/core/*`
+
+Run all tests:
+
+```bash
+bundle exec rake test
+```
+
+---
+
+## Version
+
+Current version: `0.1.0` (gem: serrano-vk)  
+Ruby requirement: `>= 3.2`

data/bin/serrano

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/serrano/cli/base"
+
+Serrano::CLI::Base.start(ARGV)

data/examples/demo_crud/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gem "serrano", path: "../.."
+gem "rackup"
+gem "sequel"
+gem "sqlite3"
+gem "webrick"
+
+

data/examples/demo_crud/Gemfile.lock

@@ -0,0 +1,31 @@
+PATH
+  remote: ../..
+  specs:
+    serrano (0.1.0)
+      rack (>= 3.2.0, < 4.0.0)
+      rackup (>= 2.3.0, < 3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    bigdecimal (4.0.1)
+    rack (3.2.5)
+    rackup (2.3.1)
+      rack (>= 3)
+    sequel (5.102.0)
+      bigdecimal
+    sqlite3 (2.9.1-x64-mingw-ucrt)
+    webrick (1.9.2)
+
+PLATFORMS
+  x64-mingw-ucrt
+
+DEPENDENCIES
+  rackup
+  sequel
+  serrano!
+  sqlite3
+  webrick
+
+BUNDLED WITH
+   2.6.9

data/examples/demo_crud/app/controllers/articles_controller.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../services/articles/index"
+require_relative "../services/articles/show"
+require_relative "../services/articles/create"
+require_relative "../services/articles/update"
+require_relative "../services/articles/destroy"
+
+class ArticlesController
+  def index(_request)
+    result = Articles::Services::Index.new.call
+
+    Serrano::Response.new(
+      status: 200,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate(result[:items].map(&:to_h))
+    )
+  end
+
+  def show(request)
+    result = Articles::Services::Show.new.call(request["id"])
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 200,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate(result[:article].to_h)
+      )
+    end
+
+    Serrano::Response.new(
+      status: 404,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+
+  def create(request)
+    result = Articles::Services::Create.new.call(request.params)
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 201,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate(result[:article].to_h)
+      )
+    end
+
+    Serrano::Response.new(
+      status: 422,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+
+  def update(request)
+    result = Articles::Services::Update.new.call(request["id"], request.params)
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 200,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate(result[:article].to_h)
+      )
+    end
+
+    Serrano::Response.new(
+      status: 422,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+
+  def destroy(request)
+    result = Articles::Services::Destroy.new.call(request["id"])
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 200,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate({ deleted: true })
+      )
+    end
+
+    Serrano::Response.new(
+      status: 422,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+end

data/examples/demo_crud/app/controllers/categories_controller.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../services/categories/index"
+require_relative "../services/categories/show"
+require_relative "../services/categories/create"
+require_relative "../services/categories/update"
+require_relative "../services/categories/destroy"
+
+class CategoriesController
+  def index(_request)
+    result = Categories::Services::Index.new.call
+
+    Serrano::Response.new(
+      status: 200,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate(result[:items].map(&:to_h))
+    )
+  end
+
+  def show(request)
+    result = Categories::Services::Show.new.call(request["id"])
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 200,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate(result[:category].to_h)
+      )
+    end
+
+    Serrano::Response.new(
+      status: 404,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+
+  def create(request)
+    result = Categories::Services::Create.new.call(request.params)
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 201,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate(result[:category].to_h)
+      )
+    end
+
+    Serrano::Response.new(
+      status: 422,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+
+  def update(request)
+    result = Categories::Services::Update.new.call(request["id"], request.params)
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 200,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate(result[:category].to_h)
+      )
+    end
+
+    Serrano::Response.new(
+      status: 422,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+
+  def destroy(request)
+    result = Categories::Services::Destroy.new.call(request["id"])
+
+    if result[:ok]
+      return Serrano::Response.new(
+        status: 200,
+        headers: { "content-type" => "application/json" },
+        body: JSON.generate({ deleted: true })
+      )
+    end
+
+    Serrano::Response.new(
+      status: 422,
+      headers: { "content-type" => "application/json" },
+      body: JSON.generate({ errors: result[:errors] })
+    )
+  end
+end

data/examples/demo_crud/app/entities/article.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "./concerns/validatable"
+
+class Article
+  include Validatable
+
+  validates :title, presence: true
+
+  def initialize(attrs = {})
+    @attrs = attrs || {}
+  end
+
+  def to_h
+    @attrs
+  end
+end

data/examples/demo_crud/app/entities/category.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "./concerns/validatable"
+
+class Category
+  include Validatable
+
+  validates :name, presence: true
+
+  def initialize(attrs = {})
+    @attrs = attrs || {}
+  end
+
+  def to_h
+    @attrs
+  end
+end