macaw_framework 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23fe3e98800399fc740bf5a76603fab28e53502d8f5041d894ecac5bef96f00c
-  data.tar.gz: 5b8f46d645b2e274d005368e9f144bca0b63eac552942ea3176172a1479ac4a4
+  metadata.gz: 7be8f35960be882dfd7d36d929a06a2ee46416e077532d6cb08809b39db41eed
+  data.tar.gz: 4ea88706237b89a02b64a7f6c73848d2b64c4ec04643e641ad6ac2711985f57d
 SHA512:
-  metadata.gz: 1757594571b01f8110c8b839c906a63488aa25120adc1b96f7a87066cbaea0473d0628398d9d134e4950d3b6dcf19ddd07bc806620608f2214404aee0950587e
-  data.tar.gz: 8326f4957ba9d8baa95603d5c4c4300339e6e4a4d6797fc34945e88d9e07dc9e102ac0ba5a0dbce90ea581f8ab7f5fc4e8d8f22c8cf6e0d2013863f2f634a0b2
+  metadata.gz: 9a91371c336e35ad1207be16504767676ef1e2125cd40ea4caba201da704d2006a7bd538b77122502c90f85550142d11fc8d1c78c7a0426dd776f8e0b57a1b90
+  data.tar.gz: 67383dfb8aecb709167d5ab92af4cc9ed821e5898b92b2f06910ed8ccc2390af6afd7cc5325b7d1acf73fe3e731edf47afbbaa760e859fb3da92cae62103d8fd

data/CHANGELOG.md

@@ -68,9 +68,14 @@
 
 - Fixing critical bug where threads were being killed and not respawning after abrupt client connection shutdown
 
-## [1.1.0] - 2023-xx-xx
+## [1.1.0] - 2023-05-20
 
 - Adding support for other SSL/TSL keys other than RSA
 - New mechanism to handle server shutdown properly
 - Improving log readability
-- Automatic logging is now optional
+- Automatic logging is now optional
+
+## [1.1.1] - 2023-05-28
+
+- Adding native cron jobs
+- Documentation improvement

data/README.md

@@ -4,6 +4,22 @@ MacawFramework is a lightweight, easy-to-use web framework for Ruby designed to
 medium-sized web applications. With support for various HTTP methods, caching, and session management, MacawFramework 
 provides developers with the essential tools to quickly build and deploy their applications.
 
+- [MacawFramework](#macawframework)
+    * [Features](#features)
+    * [Installation](#installation)
+    * [Compatibility](#compatibility)
+    * [Usage](#usage)
+        + [Basic routing: Define routes with support for GET, POST, PUT, PATCH, and DELETE HTTP methods](#basic-routing-define-routes-with-support-for-get-post-put-patch-and-delete-http-methods)
+        + [Caching: Improve performance by caching responses and configuring cache invalidation](#caching-improve-performance-by-caching-responses-and-configuring-cache-invalidation)
+        + [Session management: Handle user sessions securely with server-side in-memory storage](#session-management-handle-user-sessions-securely-with-server-side-in-memory-storage)
+        + [Configuration: Customize various aspects of the framework through the application.json configuration file, such as rate limiting, SSL support, and Prometheus integration](#configuration-customize-various-aspects-of-the-framework-through-the-applicationjson-configuration-file-such-as-rate-limiting-ssl-support-and-prometheus-integration)
+        + [Monitoring: Easily monitor your application performance and metrics with built-in Prometheus support](#monitoring-easily-monitor-your-application-performance-and-metrics-with-built-in-prometheus-support)
+        + [Cron Jobs](#cron-jobs)
+        + [Tips](#tips)
+    * [Contributing](#contributing)
+    * [License](#license)
+    * [Code of Conduct](#code-of-conduct)
+
 ## Features
 
 - Simple routing with support for GET, POST, PUT, PATCH, and DELETE HTTP methods
@@ -23,6 +39,16 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install macaw_framework
 
+## Compatibility
+
+MacawFramework is built to be highly compatible, since it uses only native Ruby code:
+
+- **MRI**: MacawFramework is compatible with Matz's Ruby Interpreter (MRI), version 2.7.0 and onwards. If you are using this version or a more recent one, you should not encounter any compatibility issues.
+
+- **TruffleRuby**: TruffleRuby is another Ruby interpreter that is fully compatible with MacawFramework. This provides developers with more flexibility in their choice of Ruby interpreter.
+
+- **JRuby**: MacawFramework is also compatible with JRuby, a version of Ruby that runs on the Java Virtual Machine (JVM).
+
 ## Usage
 
 ### Basic routing: Define routes with support for GET, POST, PUT, PATCH, and DELETE HTTP methods
@@ -122,21 +148,39 @@ end
 curl http://localhost:8080/metrics
 ```
 
+### Cron Jobs
+
+Macaw Framework supports the declaration of cron jobs right in your application code. This feature allows developers to 
+define tasks that run at set intervals, starting after an optional delay. Each job runs in a separate thread, meaning 
+your cron jobs can execute in parallel without blocking the rest of your application.
+
+Here's an example of how to declare a cron job:
+
+```ruby
+m.setup_job(interval: 5, start_delay: 5, job_name: "cron job 1") do
+  puts "i'm a cron job that runs every 5 secs!"
+end
+```
+
+Values for interval and start_delay are in seconds.
+
+**Caution: Defining a lot of jobs with low interval can severely degrade performance.**
+
 ### Tips
 
-The automatic logging and log aspect are now optional. To disable them, simply start Macaw with `custom_log` set to nil.
+- The automatic logging and log aspect are now optional. To disable them, simply start Macaw with `custom_log` set to nil.
 
 ```ruby
 MacawFramework::Macaw.new(custom_log: nil)
 ```
 
-Cache invalidation time should be specified in seconds. In order to enable caching, The application.json file
+- Cache invalidation time should be specified in seconds. In order to enable caching, The application.json file
 should exist in the app main directory and it need the `cache_invalidation` config set. It is possible to
 provide a list of strings in the property `ignore_headers`. All the client headers with the same name of any
 of the strings provided will be ignored from caching strategy. This is useful to exclude headers like 
 correlation IDs from the caching strategy.
 
-URL parameters like `...endOfUrl?key1=value1&key2=value2` can be find in the `context[:params]`
+- URL parameters like `...endOfUrl?key1=value1&key2=value2` can be find in the `context[:params]`
 
 ```ruby
 m.get('/test_params') do |context|
@@ -144,22 +188,25 @@ m.get('/test_params') do |context|
 end
 ```
 
-Rate Limit window should also be specified in seconds. Rate limit will be activated only if the `rate_limiting` config
+- Rate Limit window should also be specified in seconds. Rate limit will be activated only if the `rate_limiting` config
 exists inside `application.json`.
 
-If the SSL configuration is provided in the `application.json` file with valid certificate and key files, the TCP server
+- If the SSL configuration is provided in the `application.json` file with valid certificate and key files, the TCP server
 will be wrapped with HTTPS security using the provided certificate.
 
-The supported values for `min` and `max` in the SSL configuration are: `SSL2`, `SSL3`, `TLS1.1`, `TLS1.2` and `TLS1.3`,
+- The supported values for `min` and `max` in the SSL configuration are: `SSL2`, `SSL3`, `TLS1.1`, `TLS1.2` and `TLS1.3`,
 and the supported values for `key_type` are `RSA` and `EC`.
 
-If prometheus is enabled, a get endpoint will be defined at path `/metrics` to collect prometheus metrics. This path
+- If prometheus is enabled, a get endpoint will be defined at path `/metrics` to collect prometheus metrics. This path
 is configurable via the `application.json` file.
 
-The verb methods must always return a string or nil (used as the response), a number corresponding to the HTTP status 
+- The verb methods must always return a string or nil (used as the response), a number corresponding to the HTTP status 
 code to be returned to the client and the response headers as a Hash or nil. If an endpoint doesn't return a value or 
 returns nil for body, status code and headers, a default 200 OK status will be sent as the response.
 
+- For cron jobs without a start_delay, a value of 0 will be used. For a job without name, a unique name will be generated 
+for it.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ariasdiniz/macaw_framework. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/ariasdiniz/macaw_framework/blob/main/CODE_OF_CONDUCT.md).

data/SECURITY.md

@@ -5,9 +5,9 @@
 We are committed to addressing security issues in a timely manner. The following versions of MacawFramework are currently supported with security updates:
 
 | Version | Supported          |
-| ------- | ------------------ |
-| 1.0.x   | :white_check_mark: |
-| < 1.x   | :x:                |
+|---------| ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -24,4 +24,3 @@ Alternatively, you can send an email to aria.diniz.dev@gmail.com with the same i
 4. Once the issue is resolved, we will release a new version of MacawFramework with the necessary security fixes.
 
 Please remember to follow the project's [Code of Conduct](https://github.com/ariasdiniz/macaw_framework/blob/main/CODE_OF_CONDUCT.md) when reporting security vulnerabilities.
-

data/lib/macaw_framework/core/{server.rb → common/server_base.rb}

@@ -1,89 +1,42 @@
 # frozen_string_literal: true
 
-require_relative "../middlewares/memory_invalidation_middleware"
-require_relative "../middlewares/rate_limiter_middleware"
-require_relative "../data_filters/response_data_filter"
-require_relative "../errors/too_many_requests_error"
-require_relative "../utils/supported_ssl_versions"
-require_relative "../aspects/prometheus_aspect"
-require_relative "../aspects/logging_aspect"
-require_relative "../aspects/cache_aspect"
-require "openssl"
+require_relative "../../middlewares/memory_invalidation_middleware"
+require_relative "../../middlewares/rate_limiter_middleware"
+require_relative "../../data_filters/response_data_filter"
+require_relative "../../errors/too_many_requests_error"
+require_relative "../../utils/supported_ssl_versions"
+require_relative "../../aspects/prometheus_aspect"
+require_relative "../../aspects/logging_aspect"
+require_relative "../../aspects/cache_aspect"
 
 ##
-# Class responsible for providing a default
-# webserver.
-class Server
+# Base module for Server classes. It contains
+# methods for client handling, error handling,
+# set features and every method that is common
+# for the implementations of Servers.
+module ServerBase
   prepend CacheAspect
   prepend LoggingAspect
   prepend PrometheusAspect
-  # rubocop:disable Metrics/ParameterLists
-
-  attr_reader :context
-
-  ##
-  # Create a new instance of Server.
-  # @param {Macaw} macaw
-  # @param {Logger} logger
-  # @param {Integer} port
-  # @param {String} bind
-  # @param {Integer} num_threads
-  # @param {MemoryInvalidationMiddleware} cache
-  # @param {Prometheus::Client:Registry} prometheus
-  # @return {Server}
-  def initialize(macaw, endpoints_to_cache = nil, cache = nil, prometheus = nil, prometheus_mw = nil)
-    @port = macaw.port
-    @bind = macaw.bind
-    @macaw = macaw
-    @macaw_log = macaw.macaw_log
-    @num_threads = macaw.threads
-    @work_queue = Queue.new
-    ignored_headers = set_cache_ignored_h
-    set_features
-    @rate_limit ||= nil
-    ignored_headers ||= nil
-    @cache = { cache: cache, endpoints_to_cache: endpoints_to_cache || [], ignored_headers: ignored_headers }
-    @prometheus = prometheus
-    @prometheus_middleware = prometheus_mw
-    @workers = []
-  end
-
-  # rubocop:enable Metrics/ParameterLists
-
-  ##
-  # Start running the webserver.
-  def run
-    @server = TCPServer.new(@bind, @port)
-    @server = OpenSSL::SSL::SSLServer.new(@server, @context) if @context
-    @workers_mutex = Mutex.new
-    @num_threads.times do
-      spawn_worker
-    end
 
-    Thread.new do
-      loop do
-        sleep 10
-        maintain_worker_pool
-      end
-    end
+  private
 
-    loop do
-      @work_queue << @server.accept
-    rescue OpenSSL::SSL::SSLError => e
-      @macaw_log&.error("SSL error: #{e.message}")
-    rescue IOError, Errno::EBADF
-      break
-    end
+  def call_endpoint(name, client_data, client_ip)
+    @macaw.send(
+      name.to_sym,
+      {
+        headers: client_data[:headers],
+        body: client_data[:body],
+        params: client_data[:params],
+        client: @session[client_ip][0]
+      }
+    )
   end
 
-  ##
-  # Method Responsible for closing the TCP server.
-  def close
-    shutdown
+  def get_client_data(body, headers, parameters)
+    { body: body, headers: headers, params: parameters }
   end
 
-  private
-
   def handle_client(client)
     path, method_name, headers, body, parameters = RequestDataFiltering.parse_request_data(client, @macaw.routes)
     raise EndpointNotMappedError unless @macaw.respond_to?(method_name)
@@ -178,61 +131,4 @@ class Server
     set_session
     set_ssl
   end
-
-  def call_endpoint(name, client_data, client_ip)
-    @macaw.send(
-      name.to_sym,
-      {
-        headers: client_data[:headers],
-        body: client_data[:body],
-        params: client_data[:params],
-        client: @session[client_ip][0]
-      }
-    )
-  end
-
-  def get_client_data(body, headers, parameters)
-    { body: body, headers: headers, params: parameters }
-  end
-
-  def spawn_worker
-    @workers_mutex.synchronize do
-      @workers << Thread.new do
-        loop do
-          client = @work_queue.pop
-          break if client == :shutdown
-
-          handle_client(client)
-        end
-      end
-    end
-  end
-
-  def maintain_worker_pool
-    @workers_mutex.synchronize do
-      @workers.each_with_index do |worker, index|
-        unless worker.alive?
-          if @is_shutting_down
-            @macaw_log&.info("Worker thread #{index} finished, not respawning due to server shutdown.")
-          else
-            @macaw_log&.error("Worker thread #{index} died, respawning...")
-            @workers[index] = spawn_worker
-          end
-        end
-      end
-    end
-  end
-
-  def shutdown
-    @is_shutting_down = true
-    loop do
-      break if @work_queue.empty?
-
-      sleep 0.1
-    end
-
-    @num_threads.times { @work_queue << :shutdown }
-    @workers.each(&:join)
-    @server.close
-  end
 end

data/lib/macaw_framework/core/cron_runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+##
+# This module is responsible to set up a new thread
+# for each cron job defined
+class CronRunner
+  def initialize(macaw)
+    @logger = macaw.macaw_log
+    @macaw = macaw
+  end
+
+  ##
+  # Will start a thread for the defined cron job
+  # @param {Integer} interval
+  # @param {Integer?} start_delay
+  # @param {String} job_name
+  # @param {Proc} block
+  def start_cron_job_thread(interval, start_delay, job_name, &block)
+    raise "interval can't be <= 0 and start_delay can't be < 0!" if interval <= 0 || start_delay.negative?
+
+    @logger&.info("Starting thread for job #{job_name}")
+    start_delay ||= 0
+    thread = Thread.new do
+      name = job_name
+      interval_thread = interval
+      unless start_delay.nil?
+        @logger&.info("Job #{name} scheduled with delay. Will start running in #{start_delay} seconds.")
+        sleep(start_delay)
+      end
+
+      loop do
+        start_time = Time.now
+        @logger&.info("Running job #{name}")
+        block.call
+        @logger&.info("Job #{name} executed with success. New execution in #{interval_thread} seconds.")
+
+        execution_time = Time.now - start_time
+        sleep_time = [interval_thread - execution_time, 0].max
+        sleep(sleep_time)
+      rescue StandardError => e
+        @logger&.error("Error executing cron job with name #{name}: #{e.message}")
+      end
+    end
+    sleep(1)
+    @logger&.info("Thread for job #{job_name} started")
+    thread
+  end
+end

data/lib/macaw_framework/core/thread_server.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "common/server_base"
+require "openssl"
+
+##
+# Class responsible for providing a default
+# webserver with Ruby Threads. This Server is subject
+# to the MRI Global Interpreter Lock, thus it will use
+# only a single physical Thread. For a true multi threaded
+# server, check the RactorServer.
+class ThreadServer
+  include ServerBase
+
+  attr_reader :context
+
+  # rubocop:disable Metrics/ParameterLists
+
+  ##
+  # Create a new instance of ThreadServer.
+  # @param {Macaw} macaw
+  # @param {Logger} logger
+  # @param {Integer} port
+  # @param {String} bind
+  # @param {Integer} num_threads
+  # @param {MemoryInvalidationMiddleware} cache
+  # @param {Prometheus::Client:Registry} prometheus
+  # @return {Server}
+  def initialize(macaw, endpoints_to_cache = nil, cache = nil, prometheus = nil, prometheus_mw = nil)
+    @port = macaw.port
+    @bind = macaw.bind
+    @macaw = macaw
+    @macaw_log = macaw.macaw_log
+    @num_threads = macaw.threads
+    @work_queue = Queue.new
+    ignored_headers = set_cache_ignored_h
+    set_features
+    @rate_limit ||= nil
+    ignored_headers ||= nil
+    @cache = { cache: cache, endpoints_to_cache: endpoints_to_cache || [], ignored_headers: ignored_headers }
+    @prometheus = prometheus
+    @prometheus_middleware = prometheus_mw
+    @workers = []
+  end
+
+  # rubocop:enable Metrics/ParameterLists
+
+  ##
+  # Start running the webserver.
+  def run
+    @server = TCPServer.new(@bind, @port)
+    @server = OpenSSL::SSL::SSLServer.new(@server, @context) if @context
+    @workers_mutex = Mutex.new
+    @num_threads.times do
+      spawn_worker
+    end
+
+    Thread.new do
+      loop do
+        sleep 10
+        maintain_worker_pool
+      end
+    end
+
+    loop do
+      @work_queue << @server.accept
+    rescue OpenSSL::SSL::SSLError => e
+      @macaw_log&.error("SSL error: #{e.message}")
+    rescue IOError, Errno::EBADF
+      break
+    end
+  end
+
+  ##
+  # Method Responsible for closing the TCP server.
+  def close
+    shutdown
+  end
+
+  private
+
+  def spawn_worker
+    @workers_mutex.synchronize do
+      @workers << Thread.new do
+        loop do
+          client = @work_queue.pop
+          break if client == :shutdown
+
+          handle_client(client)
+        end
+      end
+    end
+  end
+
+  def maintain_worker_pool
+    @workers_mutex.synchronize do
+      @workers.each_with_index do |worker, index|
+        unless worker.alive?
+          if @is_shutting_down
+            @macaw_log&.info("Worker thread #{index} finished, not respawning due to server shutdown.")
+          else
+            @macaw_log&.error("Worker thread #{index} died, respawning...")
+            @workers[index] = spawn_worker
+          end
+        end
+      end
+    end
+  end
+
+  def shutdown
+    @is_shutting_down = true
+    loop do
+      break if @work_queue.empty?
+
+      sleep 0.1
+    end
+
+    @num_threads.times { @work_queue << :shutdown }
+    @workers.each(&:join)
+    @server.close
+  end
+end

data/lib/macaw_framework/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MacawFramework
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

data/lib/macaw_framework.rb

@@ -4,9 +4,11 @@ require_relative "macaw_framework/errors/endpoint_not_mapped_error"
 require_relative "macaw_framework/middlewares/prometheus_middleware"
 require_relative "macaw_framework/data_filters/request_data_filtering"
 require_relative "macaw_framework/middlewares/memory_invalidation_middleware"
-require_relative "macaw_framework/core/server"
+require_relative "macaw_framework/core/cron_runner"
+require_relative "macaw_framework/core/thread_server"
 require_relative "macaw_framework/version"
 require "prometheus/client"
+require "securerandom"
 require "logger"
 require "socket"
 require "json"
@@ -18,11 +20,11 @@ module MacawFramework
   class Macaw
     ##
     # Array containing the routes defined in the application
-    attr_reader :routes, :port, :bind, :threads, :macaw_log, :config
+    attr_reader :routes, :port, :bind, :threads, :macaw_log, :config, :jobs
 
     ##
     # @param {Logger} custom_log
-    def initialize(custom_log: Logger.new($stdout), server: Server)
+    def initialize(custom_log: Logger.new($stdout), server: ThreadServer)
       begin
         @routes = []
         @macaw_log ||= custom_log
@@ -100,6 +102,19 @@ module MacawFramework
       map_new_endpoint("delete", cache, path, &block)
     end
 
+    ##
+    # Spawn and start a thread running the defined cron job.
+    # @param {Integer} interval
+    # @param {Integer?} start_delay
+    # @param {String} job_name
+    # @param {Proc} block
+    def setup_job(interval: 60, start_delay: nil, job_name: "job_#{SecureRandom.uuid}", &block)
+      @cron_runner ||= CronRunner.new(self)
+      @jobs ||= []
+      @cron_runner.start_cron_job_thread(interval, start_delay, job_name, &block)
+      @jobs << job_name
+    end
+
     ##
     # Starts the web server
     def start!

data/sig/cron_runner.rbs

@@ -0,0 +1,6 @@
+class CronRunner
+  @logger: Logger?
+  @macaw: MacawFramework::Macaw
+
+  def start_cron_job_thread: -> Thread
+end

data/sig/macaw_framework/macaw.rbs

@@ -14,6 +14,7 @@ module MacawFramework
 
     attr_reader bind: String
     attr_reader config: Hash[String, untyped]
+    attr_reader jobs: Array[String]
     attr_reader macaw_log: Logger?
     attr_reader port: Integer
     attr_reader routes: Array[String]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: macaw_framework
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Aria Diniz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-05-20 00:00:00.000000000 Z
+date: 2023-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prometheus-client
@@ -46,7 +46,9 @@ files:
 - lib/macaw_framework/aspects/cache_aspect.rb
 - lib/macaw_framework/aspects/logging_aspect.rb
 - lib/macaw_framework/aspects/prometheus_aspect.rb
-- lib/macaw_framework/core/server.rb
+- lib/macaw_framework/core/common/server_base.rb
+- lib/macaw_framework/core/cron_runner.rb
+- lib/macaw_framework/core/thread_server.rb
 - lib/macaw_framework/data_filters/log_data_filter.rb
 - lib/macaw_framework/data_filters/request_data_filtering.rb
 - lib/macaw_framework/data_filters/response_data_filter.rb
@@ -58,8 +60,8 @@ files:
 - lib/macaw_framework/utils/http_status_code.rb
 - lib/macaw_framework/utils/supported_ssl_versions.rb
 - lib/macaw_framework/version.rb
-- macaw_logo.png
 - main/CODEOWNERS
+- sig/cron_runner.rbs
 - sig/http_status_code.rbs
 - sig/logging_aspect.rbs
 - sig/macaw_framework.rbs