ru.Bee 1.11.1 → 2.1.0

data/lib/tests/models/user_model_test.rb

@@ -345,4 +345,98 @@ zip: '555555')
       end
     end
   end
+
+  describe 'pubsub' do
+    describe 'when Rubee::PubSub::Subscriber is included' do
+      before { User.include(Rubee::PubSub::Subscriber) }
+
+      it 'reveals sub method' do
+        _(User.respond_to?(:sub)).must_equal(true)
+      end
+
+      it 'reveals unsub method' do
+        _(User.respond_to?(:unsub)).must_equal(true)
+      end
+    end
+
+    describe 'when Rubee::PubSub::Publisher is included' do
+      before { User.include(Rubee::PubSub::Publisher) }
+
+      it 'reveals pub method' do
+        _(User.respond_to?(:pub)).must_equal(true)
+      end
+    end
+
+    describe '.sub' do
+      before do
+        User.include(Rubee::PubSub::Subscriber)
+        User.include(Rubee::PubSub::Publisher)
+      end
+
+      user = User.create(email: 'ok-test@test.com', password: '123')
+
+      describe 'when sub with channel and args' do
+        it 'returns true' do
+          _(User.sub("ok", [user.id.to_s])).must_equal(true)
+
+          User.unsub("ok", [user.id.to_s])
+          user.destroy
+        end
+      end
+    end
+
+    describe '.unsub' do
+      before do
+        User.include(Rubee::PubSub::Subscriber)
+        User.include(Rubee::PubSub::Publisher)
+      end
+
+      describe 'when unsub with channel and args' do
+        it 'returns true' do
+          _(User.unsub("ok", ["123456"])).must_equal(true)
+        end
+      end
+    end
+
+    describe 'pub flow' do
+      describe 'when pub with channel and args' do
+        after do
+          User.destroy_all(cascade: true)
+        end
+
+        it 'fan out ouput' do
+          User.include(Rubee::PubSub::Subscriber)
+          User.include(Rubee::PubSub::Publisher)
+
+          user_one = User.create(email: 'ok-test1@test.com', password: '123')
+          user_two = User.create(email: 'ok-test@2test.com', password: '123')
+          user_three = User.create(email: 'ok-test3@test.com', password: '123')
+
+          User.singleton_class.define_method(:on_pub) do |channel, *args, **options|
+            id = args.first
+            user = User.find(id)
+            if user
+              user.update(password: '321')
+            else
+              raise "User with id=#{id} not found"
+            end
+          end
+
+          User.sub("ok", [user_one.id.to_s])
+          User.sub("ok", [user_two.id.to_s])
+          User.sub("ok", [user_three.id.to_s])
+
+          User.pub("ok", message: "hello")
+
+          User.unsub("ok", [user_one.id.to_s])
+          User.unsub("ok", [user_two.id.to_s])
+          User.unsub("ok", [user_three.id.to_s])
+
+          _(user_one.reload.password).must_equal('321')
+          _(user_two.reload.password).must_equal('321')
+          _(user_three.reload.password).must_equal('321')
+        end
+      end
+    end
+  end
 end

data/lib/tests/test_helper.rb

@@ -39,3 +39,9 @@ ensure
   $stdout = old_stdout
 end
 
+def raise_error
+  yield
+rescue => e
+  e
+end
+

data/readme.md

@@ -6,9 +6,9 @@
 ![GitHub Repo stars](https://img.shields.io/github/stars/nucleom42/rubee?style=social)
 
 
-# <img src="lib/images/rubee.svg" alt="RUBEE" height="40"> ... RUBEE
+# <img src="lib/images/rubee.svg" alt="ru.Bee" height="40"> ... ru.Bee
 
-Rubee is a Ruby-based web framework designed to streamline the development of modular monolith web applications. \
+ru.Bee is a Ruby-based web framework designed to streamline the development of modular monolith web applications. \
 Under the hood, it leverages the power of Ruby and Rack backed by Puma, offering a clean, efficient, and flexible architecture. \
 It offers a structured approach to building scalable, maintainable, and React-ready projects, \
 making it an ideal choice for developers seeking a balance between monolithic simplicity and modular flexibility.
@@ -17,9 +17,13 @@ Want to get a quick API server up and runing? You can do it for real quick!
 <br />
 [![Watch the demo](https://img.youtube.com/vi/ko7H70s7qq0/hqdefault.jpg)](https://www.youtube.com/watch?v=ko7H70s7qq0)
 
+Starting from ru.Bee 2.0.0, ru.Bee supports Websocket, which is a feature that allows you to build real-time applications with ease. \
+<br />
+[![Watch the demo](https://img.youtube.com/vi/gp8IheKBNm4/hqdefault.jpg)](https://www.youtube.com/watch?v=gp8IheKBNm4)
+
 ## Production ready
 
-Take a look on the rubee demo site with all documentation stored in there: https://rubee.dedyn.io/
+Take a look on the ru.Bee demo site with all documentation stored in there: https://rubee.dedyn.io/
 Want to explore how it built? https://github.com/nucleom42/rubee-site
 
 ## Stress tested
@@ -41,17 +45,17 @@ Transfer/sec:    140.07KB
 - Average latency: ~305 ms
 - Total requests handled: 9,721
 - Hardware: Raspberry Pi 5(8 Gb) (single board computer)
-- Server: Rubee app hosted via Nginx + HTTPS
+- Server: ru.Bee app hosted via Nginx + HTTPS
 
-This demonstrates RUBEE’s efficient architecture and suitability for lightweight deployments — even on low-power hardware.
+This demonstrate ru.Bee’s efficient architecture and suitability for lightweight deployments — even on low-power hardware.
 
 ## Comparison
-Here below is a **short web frameworks comparison** built with Ruby, so you can evaluate your choice with RUBEE.
+Here below is a **short web frameworks comparison** built with Ruby, so you can evaluate your choice with ru.Bee.
 
 **Disclaimer:**
 The comparison is based on a very generic and subjective information open in the Internet and is not a real benchmark. The comparison is aimed to give you a general idea of the differences between the frameworks and Rubee and not to compare the frameworks directly.
 
-| Feature / Framework | **Rubee** | Rails | Sinatra | Hanami | Padrino | Grape |
+| Feature / Framework | **ru.Bee** | Rails | Sinatra | Hanami | Padrino | Grape |
 |---------------------|-----------|-------|---------|--------|---------|-------|
 | **React readiness** | Built-in React integration (route generator can scaffold React components that fetch data via controllers) | React via webpacker/importmap, but indirect | No direct React support | Can integrate React | Can integrate via JS pipelines | API-focused, no React support |
 | **Routing style**   | Explicit, file-based routes with clear JSON/HTML handling | DSL, routes often implicit inside controllers | Explicit DSL, inline in code | Declarative DSL | Rails-like DSL | API-oriented DSL |
@@ -73,7 +77,9 @@ The comparison is based on a very generic and subjective information open in the
 - [Database](#database)
 - [Views](#views)
 - [Hooks](#hooks)
+- [Validations](#validations)
 - [JWT based authentification](#jwt-based-authentification)
+- [OAuth2 based authentification](#oauth-authentification)
 - [Rubee commands](#rubee-commands)
 - [Generate commands](#generate-commands)
 - [Migration commands](#migration-commands)
@@ -82,12 +88,10 @@ The comparison is based on a very generic and subjective information open in the
 - [Background jobs](#background-jobs)
 - [Modular](#modualar-application)
 - [Logger](#logger)
+- [Websocket](#websocket)
 
 You can read it on the demo: [site](https://rubee.dedyn.io/)
 
-🚧 The doc site is on update mode now. We are working on it.
-Please refer to the documentation shown below.
-
 ## Features
 
 Lightweight – A minimal footprint focused on serving Ruby applications efficiently.
@@ -105,9 +109,9 @@ Databases – Supports SQLite3, PostgreSQL, MySQL, and more via the Sequel gem.
 <br>
 Views – JSON, ERB, and plain HTML out of the box.
 <br>
-React Ready – React is supported as a first-class Rubee view engine.
+React Ready – React is supported as a first-class ru.Bee view engine.
 <br>
-Bundlable – Charge your Rubee app with any gem you need. Update effortlessly via Bundler.
+Bundlable – Charge your ru.Bee app with any gem you need. Update effortlessly via Bundler.
 <br>
 ORM-agnostic – Models are native ORM objects, but you can use them as blueprints for any data source.
 <br>
@@ -122,10 +126,14 @@ Asyncable – Plug in async adapters and use any popular background job engine.
 Console – Start an interactive console and reload on the fly.
 <br>
 Background Jobs – Schedule and process background jobs using your preferred async stack.
+<br>
+Websocket – Serve and handle WebSocket connections.
+<br>
+Logger – Use any logger you want.
 
 ## Installation
 
-1. Install RUBEE
+1. Install ru.Bee
 ```bash
 gem install ru.Bee
 ```
@@ -150,7 +158,7 @@ Make sure:
 bundle install
 ```
 
-4. Run RUBEE server. Default port is 7000
+4. Run RUBER server. Default port is 7000
 ```bash
 rubee start # or rubee start_dev for development
 
@@ -215,7 +223,7 @@ This will generate the following files
 [Back to content](#content)
 
 ## Model
-Model in RUBEE is just simple ruby object that can be serilalized in the view
+Model in ru.Bee is just simple ruby object that can be serilalized in the view
 in the way it required (ie json).
 Here below is a simple example on how it can be used by rendering json from in memory object
 
@@ -354,7 +362,7 @@ irb(main):023> User.all
 => []
 ```
 
-Use complex queries chains and when ready serialize it back to Rubee object.
+Use complex queries chains and when ready serialize it back to ru.Bee object.
 ```Ruby
 # user model
 class User < Rubee::SequelObject
@@ -391,7 +399,7 @@ irb(main):009>  .where(comment_id: Comment.where(text: "test").last.id)
 irb(main):010>  .then { |dataset| Comment.serialize(dataset) }
 => [#<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>]
 ```
-This is recommended when you want to run one query and serialize it back to Rubee object only once.
+This is recommended when you want to run one query and serialize it back to ru.Bee object only once.
 So it may safe some resources.
 
 [Back to content](#content)
@@ -407,7 +415,7 @@ If you feel comfortable you can play with retry configuration parameters:
   config.db_busy_timeout = { env:, value: 1000 } # this is busy timeout in ms, before raising bussy error
 ```
 
-For Rubee model class persist methods create and update retry will be added automatically. However, \
+For ru.Bee model class persist methods create and update retry will be added automatically. However, \
 if you want to do it with Sequel dataset you need to do it yourself:
 
 ```ruby
@@ -416,7 +424,7 @@ if you want to do it with Sequel dataset you need to do it yourself:
 [Back to content](#content)
 
 ## Routing
-Rubee uses explicit routes. In the routes.rb yout can define routes for any of the main HTTP methods. \
+ru.Bee uses explicit routes. In the routes.rb yout can define routes for any of the main HTTP methods. \
 You can also add any matched parameter denoted by a pair of `{ }` in the path of the route. \
 Eg. `/path/to/{a_key}/somewhere`
 
@@ -442,7 +450,7 @@ route.{http_method} {path}, to: "{controller}#{action}",
 ```
 
 ### Defining Model attributes in routes
-One of Rubee's unique traits is where we can define our models for generation. \
+One of ru.Bee's unique traits is where we can define our models for generation. \
 You've seen above one possible way you can set up.
 
 ```ruby
@@ -571,13 +579,13 @@ Will generate:
 
 ### Modualar application
 
-You can also use RUBEE to create modular applications.\
+You can also use ru.Bee to create modular applications.\
 And attach as many subprojects you need.
 Main philosophy of attach functinality is to keep the main project clean and easy to maintain. It will still\
 share data with the main app. So where to define a border between the main app and subprojects is up to developer.
 Howerver by attching new subproject you will get a new folder and files configured and namespaced respectively.
 
-So if you need to extend your main app with a separate project, you can do it easily in RUBEE.
+So if you need to extend your main app with a separate project, you can do it easily in ruBEE.
 1. Attach new subrpoject
 
 ```bash
@@ -648,7 +656,7 @@ rubee start # or rubee start_dev for development
 [Back to content](#content)
 
 ## Views
-View in RUBEE is just a plain html/erb/react file that can be rendered from the controller.
+View in ru.Bee is just a plain html/erb/react file that can be rendered from the controller.
 
 ## Templates over erb
 
@@ -793,7 +801,7 @@ function Users() {
 
 ## Object hooks
 
-In RUBEE by extending Hookable module any Ruby object can be charged with hooks (logic),
+In ru.Bee by extending Hookable module any Ruby object can be charged with hooks (logic),
 that can be executed before, after and around a specific method execution.
 
 Here below a controller example. However it can be used in any Ruby object, like Model etc.
@@ -858,6 +866,88 @@ world!
 
 [Back to content](#content)
 
+## Validations
+
+In ru.Bee any class can be charged with validations. This is done by including Validatable module.
+Please note, ru.Bee model is validatable by default. No need to include it explicitly.
+```ruby
+class Foo
+  include Rubee::Validatable
+
+  attr_accessor :name, :age
+
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+
+  validate do |foo|
+    foo
+      .required(:name, required: 'Name is required')
+      .type(String, type: 'must be a string')
+      .condition(->{ foo.name.length > 2 }, length: 'Name must be at least 3 characters long')
+
+    foo
+      .required(:age, required: 'Age is required')
+      .type(Integer, type: 'must be an integer')
+      .condition(->{ foo.age > 18 }, age: 'You must be at least 18 years old')
+  end
+end
+```
+```bash
+    irb(main):068> Foo.new("Joe", "20")
+    =>
+    #<Foo:0x0000000120d7f778
+     @__validation_state=#<Rubee::Validatable::State:0x0000000120d7f700 @errors={age: {type: "must be an integer"}}, @valid=false>,
+     @age="20",
+     @name="Joe">
+    irb(main):069> foo = Foo.new("Joe", 11)
+    =>
+    #<Foo:0x0000000105f2b0b0
+    ...
+    irb(main):070> foo.valid?
+    => false
+    irb(main):071> foo.errors
+    => {age: {age: "You must be at least 18 years old"}}
+    irb(main):072> foo.age=20
+    => 20
+    irb(main):073> foo.valid?
+    => true
+```
+Model example
+```ruby
+class User < Rubee::SequelObject
+  attr_accessor :id, :email, :password, :created, :updated
+
+    validate do |user|
+     user
+       .required(:email, required: 'Email is required')
+       .condition(
+         ->{ user.email.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i) }, email: 'Wrong email format'
+       )
+    end
+    validate_before_persist! # This will validate and raise error in case invalid before saving to DB
+end
+```
+```bash
+irb(main):089> user = User.new(email: "wrong", password: 123)
+=> #<User:0x000000010cda23b8 @email="wrong", @password=123>
+irb(main):090> user.valid?
+=> false
+irb(main):091> user.errors
+=> {email: {email: "Wrong email format"}}
+irb(main):091> user.save
+...sequel_object.rb:229:in 'block in Rubee::SequelObject.validate_before_persist!': {email: {email: "Wrong email format"}} (Rubee::Validatable::Error)
+irb(main):092> user.email = "ok@ok.com"
+=> "ok@ok.com"
+irb(main):094> user.valid?
+=> true
+irb(main):095> user.save
+=> true
+
+```
+[Back to content](#content)
+
 ## JWT based authentification
 
 Charge you rpoject with token based authentification system and customize it for your needs.
@@ -874,7 +964,7 @@ Feel free to customize it in the /db/create_users.rb file before running migrati
 Then in the controller you can include the AuthTokenable module and use its methods:
 ```ruby
 class UsersController < Rubee::BaseController
-  include AuthTokenable
+  include Rubee::AuthTokenable
   # List methods you want to restrict
   auth_methods :index # unless the user is authentificated it will return unauthentificated
 
@@ -907,10 +997,103 @@ class UsersController < Rubee::BaseController
   end
 end
 ```
+## OAuth authentification
+If you want to plug in the OAuth 2.0 authentication, you can use the following code using OAuth2 gem:
+First thing you need to do is to add the gem to your Gemfile
+```bash
+gem 'oauth2'
+```
+Then use down below code as an example and add yours to your controller
+```ruby
+class UsersController < Rubee::BaseController
+  include Rubee::AuthTokenable
+
+  REDIRECT_URI = 'https://mysite.com/users/outh_callback'
+  CLIENT_ID = ENV['GOOGLE_CLIENT_ID']
+  CLIENT_SECRET = ENV['GOOGLE_CLIENT_SECRET']
+
+  # GET /login (login form page)
+  def edit
+    response_with
+  end
+
+  # POST /users/login (login logic)
+  def login
+    Rubee::Logger.info(message: "Login attempt for user #{params[:email]}")
+    if authentificate! # AuthTokenable method that init @token_header
+      Rubee::Logger.info(message: "Successful login for user #{@authentificated_user.email}")
+      response_with(type: :redirect, to: "/sections", headers: @token_header)
+    else
+      @error = "Wrong email or password"
+      response_with(render_view: "users_edit")
+    end
+  end
+
+  # GET /users/outh_login
+  def outh_login
+    response_with(
+      type: :redirect,
+      to: auth_client.auth_code.authorize_url(
+        redirect_uri: REDIRECT_URI,
+        scope: 'email profile openid'
+      )
+    )
+  end
+
+  # GET /users/outh_callback
+  def outh_callback
+    code = params[:code]
+    token = auth_client.auth_code.get_token(code, redirect_uri: REDIRECT_URI)
+    user_info = JSON.parse(token.get('https://www.googleapis.com/oauth2/v1/userinfo?alt=json').body)
+    Rubee::Logger.debug(object: user_info, method: "outh_callback", class: "UsersController")
+
+    user = User.where(email: user_info['email'])&.last
+    unless user
+      raise "User with email #{user_info['email']} not found"
+    end
+
+    params[:email] = user_info['email']
+    params[:password] = user.password
+
+    if authentificate! # AuthTokenable method that init @token_header
+      Rubee::Logger.info(message: "Successful Outh login for user #{@authentificated_user.email}")
+      response_with(type: :redirect, to: "/sections", headers: @token_header)
+    else
+      @error = "Something went wrong"
+      response_with(render_view: "users_edit")
+    end
+  rescue OAuth2::Error => e
+    @error = "OAuth login failed"
+    response_with(render_view: "users_edit")
+  rescue StandardError => e
+    @error = "Something went wrong"
+    response_with(render_view: "users_edit")
+  end
+
+  # POST /users/logout (logout logic)
+  def logout
+    unauthentificate! # AuthTokenable method aimed to handle logout action.
+    # Make sure @zeroed_token_header is paRssed within headers options
+    response_with(type: :redirect, to: "/login", headers: @zeroed_token_header)
+  end
+
+  private
+
+  def auth_client
+    @client ||= OAuth2::Client.new(
+      CLIENT_ID,
+      CLIENT_SECRET,
+      site: 'https://accounts.google.com',
+      authorize_url: '/o/oauth2/auth',
+      token_url: 'https://oauth2.googleapis.com/token'
+    )
+  end
+end
+```
 
 [Back to content](#content)
 
-## Rubee commands
+## ru.Bee commands
 ```bash
 rubee start # start the server
 rubee start_dev # start the server in dev mode, which restart server on changes
@@ -932,7 +1115,7 @@ rubee db run:create_apples # where create_apples is the name of the migration fi
 rubee db structure # generate migration file for the database structure
 ```
 
-## Rubee console
+## ru.Bee console
 ```bash
 rubee console # start the console
 # you can reload the console by typing reload, so it will pick up latest changes
@@ -947,7 +1130,7 @@ rubee test auth_tokenable_test.rb # run specific tests
 [Back to content](#content)
 
 
-If you want to run any RUBEE command within a specific ENV make sure you added it before a command.
+If you want to run any ru.Bee command within a specific ENV make sure you added it before a command.
 For instance if you want to run console in test environment you need to run the following command
 
 ```bash
@@ -1079,9 +1262,126 @@ When you trigger the controller action, the logs will look like this:
 
 [Back to content](#content)
 
+## Websocket
+
+With ru.Bee 2.0.0 you can use Websocket with ease!
+
+Here are steps to get started:
+1. Make sure redis server is installed and running
+````bash
+sudo apt-get install -y redis # linux
+brew install redis # osx
+````
+2. Enable websocket and redis to your Gemfile
+```bash
+gem 'ru.Bee'
+gem 'redis'
+gem 'websocket'
+```
+3. Add the redis url to your configuration file, unless it connects to 127.0.0.1:6379
+```ruby
+# config/base_configuration.rb
+Rubee::Configuration.setup(env=:development) do |config|
+#...
+  config.redis_url = { url: "redis://localhost:6378/0", env: }
+end
+```
+3. Add webscoket entry connection route
+```ruby
+# config/routes.rb
+Rubee::Router.draw do |router|
+#...
+  router.get('/ws', to: 'users#websocket') # entry point to start websocket session
+  # So, const ws = new WebSocket("ws://website/ws"); on the client side, should establish the connection
+end
+```
+4. Make model pubsubable
+```ruby
+# app/models/user.rb
+class User < Rubee::BaseModel
+  include Rubee::PubSub::Publisher
+  include Rubee::PubSub::Subscriber
+  #...
+end
+```
+5. Enable websocket in your controller and implement required methods
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < Rubee::BaseController
+  attach_websocket! # this will handle websocket connections and direct them to the controller methods: publish, subscribe, unsubscribe
+
+
+  # Subscribe is expected to get next params from the client:
+  # { action: 'subscribe', 'channel': 'default', 'id': '123', 'subscriber': 'User' }
+  # where
+  # - action corresponds to the method name
+  # - channel is the name of the channel
+  # - id is the id of the user
+  # - subscriber is the name of the model
+  def subscribe
+    channel = params[:channel]
+    sender_id = params[:options][:id] # id moved to options
+    io = params[:options][:io] # io is a websocket connection
+
+    User.sub(channel, sender_id, io) do |channel, args| # subscribe the user for the channel updates
+      websocket_connections.register(channel, args[:io]) # register the websocket connection
+    end
+    # return websocket response
+    response_with(object: { type: 'system', channel: params[:channel], status: :subscribed }, type: :websocket)
+  rescue StandardError => e
+    response_with(object: { type: 'system', error: e.message }, type: :websocket)
+  end
+
+  # Unsubscribe is expected to get next params from the client:
+  # { action: 'unsubscribe', 'channel': 'default', 'id': '123', 'subscriber': 'User' }
+  # where
+  # - action corresponds to the method name
+  # - channel is the name of the channel
+  # - id is the id of the user
+  # - subscriber is the name of the model
+  def unsubscribe
+    channel = params[:channel]
+    sender_id = params[:options][:id]
+    io = params[:options][:io]
+
+    User.unsub(channel, sender_id, io) do |channel, args|
+      websocket_connections.remove(channel, args[:io])
+    end
+
+    response_with(object: params.merge(type: 'system', status: :unsubscribed), type: :websocket)
+  rescue StandardError => e
+    response_with(object: { type: 'system', error: e.message }, type: :websocket)
+  end
+  # Publish is expected to get next params from the client:
+  # { action: 'publish', 'channel': 'default', 'message': 'Hello world', 'id': '123', 'subscriber': 'User' }
+  # where
+  # - action corresponds to the method name
+  # - channel is the name of the channel
+  # - id is the id of the user
+  # - subscriber is the name of the model
+  def publish
+    args = {}
+    User.pub(params[:channel], message: params[:message]) do |channel|
+      # Here we pack args with any additional data client might need
+      user = User.find(params[:options][:id])
+      args[:message] = params[:message]
+      args[:sender] = params[:options][:id]
+      args[:sender_name] = user.email
+      websocket_connections.stream(channel, args)
+    end
+
+    response_with(object: { type: 'system', message: params[:message], status: :published }, type: :websocket)
+  rescue StandardError => e
+    response_with(object: { type: 'system', error: e.message }, type: :websocket)
+  end
+end
+```
+If you are interested to see chat app example, please check [chat](https://github.com/nucleom42/rubee-chat)
+
+[Back to content](#content)
 ### Contributing
 
-If you are interested in contributing to RUBEE,
+If you are interested in contributing to ru.Bee,
 please read the [Contributing]()https://github.com/nucleom42/rubee/blob/main/contribution.md) guide.
 Also feel free to open an [issue](https://github.com/nucleom42/rubee/issues) if you apot one.
 Have an idea or you wnat to discuss something?