macaw_framework 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b35cc5b2fba0adc8ded0f76db41699323cc3957d54382d19e554d0e3dc77f51
-  data.tar.gz: bcd983f6afe8b8864b5d2c012c120ead8290b521ed66f49477f8defb7eed2ede
+  metadata.gz: 03ac2a8df24de8757381abc1e9a85f7854ac71a49b44d51aa7a23f1d42f95380
+  data.tar.gz: 4431ce9ab63887660aaa5cc464c00a1dd3a81b08cf4f99bb53926d0aec440fc2
 SHA512:
-  metadata.gz: 9a7f7ef95d76e906b706a036d8cb299ba1b5e3be607ba8cdc13da216b11665b019635bca062ac83fc3067a18ab36148df12d3af2bdbc0fbe42fa3a8e0cb2c018
-  data.tar.gz: 56a97dff9ddac5f4142b82d441de3264d4044ace0f8f9496a2e0f49a8e384c6cf57ed705bcf68dd051c536b0dc4e4b9a643161f6563a7bcfe095f2b6f691e5ff
+  metadata.gz: 7f981191cafd8504428de742979979a82ce1609c69ab08afc9f0b8e131381d12cc298b9b7447679b1611719605b825fcf409c9b4afee2b0d0f3a4fa8f28b5c79
+  data.tar.gz: cda629f9c4c779d11712c18dd5f9b7c8c90805688630d75c14b7fcd7c485b3cdcb2ea2386b5f6bcde62296a7b283337ee45418a08b67e61686f23ef18bf56bb2

data/.rubocop.yml

@@ -26,3 +26,6 @@ Metrics/ParameterLists:
 
 Metrics/PerceivedComplexity:
   Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false

data/CHANGELOG.md

@@ -41,3 +41,9 @@
 - Implemented a middleware for rate limiting to prevent DoS attacks
 - Improvement of caching strategy to ignore optional headers
 - First production-ready version
+
+## [1.0.1] - 2023-05-03
+
+- Introducing server-side session management
+- Fixing a bug with cache
+- Improving README

data/README.md

@@ -1,8 +1,17 @@
 # MacawFramework
 
-This is a framework for developing web applications. Please have in mind that this is still a work in progress and
-it is strongly advised to not use it for production purposes for now. Actually it supports only HTTP. and HTTPS/SSL
-support will be implemented soon. Anyone who wishes to contribute is welcome.
+MacawFramework is a lightweight, easy-to-use web framework for Ruby designed to simplify the development of small 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.
+
+## Features
+
+- Simple routing with support for GET, POST, PUT, PATCH, and DELETE HTTP methods
+- Caching middleware for improved performance
+- Session management with server-side in-memory storage
+- Basic rate limiting and SSL support
+- Prometheus integration for monitoring and metrics
+- Lightweight and easy to learn
 
 ## Installation
 
@@ -16,10 +25,56 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-The usage of the framework still very simple. Actually it support 5 HTTP verbs: GET, POST, PUT, PATCH and DELETE.
+### Basic routing: Define routes with support for GET, POST, PUT, PATCH, and DELETE HTTP methods
+
+```ruby
+require 'macaw_framework'
+
+m = MacawFramework::Macaw.new
+
+m.get('/hello_world') do |_context|
+  return "Hello, World!", 200, {"Content-Type" => "text/plain"}
+end
+
+m.post('/submit_data/:path_variable') do |context|
+  context[:body] # Client body data
+  context[:params] # Client params, like url parameters or variables
+  context[:headers] # Client headers
+  context[:params][:path_variable] # The defined path variable can be found in :params
+  context[:client] # Client session
+end
+
+m.start!
+
+```
+
+### Caching: Improve performance by caching responses and configuring cache invalidation
+
+```ruby
+m.get('/cached_data', cache: true) do |context|
+# Retrieve data
+end
+```
 
-The default server port is 8080. To choose a different port, create a file with the name `application.json` 
-in the same directory of the script that will start the application with the following content:
+### Session management: Handle user sessions securely with server-side in-memory storage
+
+```ruby
+m.get('/login') do |context|
+  # Authenticate user
+  context[:session][:user_id] = user_id
+end
+
+m.get('/dashboard') do |context|
+  # Check if the user is logged in
+  if context[:session][:user_id]
+    # Show dashboard
+  else
+    # Redirect to login
+  end
+end
+```
+
+### Configuration: Customize various aspects of the framework through the application.json configuration file, such as rate limiting, SSL support, and Prometheus integration
 
 ```json
 {
@@ -28,68 +83,54 @@ in the same directory of the script that will start the application with the fol
     "bind": "localhost",
     "threads": 10,
     "cache": {
-      "cache_invalidation": 3600
+      "cache_invalidation": 3600,
+      "ignore_headers": [
+        "header-to-be-ignored-from-caching-strategy",
+        "another-header-to-be-ignored-from-caching-strategy"
+      ]
     },
     "prometheus": {
       "endpoint": "/metrics"
     },
     "rate_limiting": {
       "window": 10,
-      "max_requests": 3,
-      "ignore_headers": [
-        "header-to-be-ignored-from-caching-strategy",
-        "another-header-to-be-ignored-from-caching-strategy"
-      ]
+      "max_requests": 3
     },
     "ssl": {
-      "ssl": {
-        "cert_file_name": "path/to/cert/file/file.crt",
-        "key_file_name": "path/to/cert/key/file.key"
-      }
+      "cert_file_name": "path/to/cert/file/file.crt",
+      "key_file_name": "path/to/cert/key/file.key"
     }
   }
 }
 ```
 
+### Monitoring: Easily monitor your application performance and metrics with built-in Prometheus support
+
+```shell
+curl http://localhost:8080/metrics
+```
+
+### Tips
+
 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.
 
-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
-will be wrapped with HTTPS security using the provided certificate.
-
-Example of usage:
+URL parameters like `...endOfUrl?key1=value1&key2=value2` can be find in the `context[:params]`
 
 ```ruby
-require 'macaw_framework'
-require 'json'
-
-m = MacawFramework::Macaw.new
-
-m.get('/hello_world', cache: true) do |context|
-  context[:body] # Returns the request body as string
-  context[:params] # Returns query parameters and path variables as a hash
-  context[:headers] # Returns headers as a hash
-  return JSON.pretty_generate({ hello_message: 'Hello World!' }), 200, {"Content-Type" => "application/json"}
-end
-
-m.post('/hello_world/:path_variable') do |context|
-  context[:body] # Returns the request body as string
-  context[:params] # Returns query parameters and path variables as a hash
-  context[:headers] # Returns headers as a hash
-  context[:params][:path_variable] # The defined path variable can be found in :params
-  return JSON.pretty_generate({ hello_message: 'Hello World!' }), 200
+m.get('/test_params') do |context|
+  context[:params]["key1"] # returns: value1
 end
-
-m.start!
 ```
 
-The example above starts a server and creates a GET endpoint at localhost/hello_world.
+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
+will be wrapped with HTTPS security using the provided certificate.
 
 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.

data/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.x   | :x:                |
+
+
+## Reporting a Vulnerability
+
+If you find a vulnerability, please open an issue or send an e-mail to aria.diniz.dev@gmail.com

data/lib/macaw_framework/aspects/cache_aspect.rb

@@ -4,7 +4,7 @@
 # Aspect that provide cache for the endpoints.
 module CacheAspect
   def call_endpoint(cache, *args)
-    return super(*args) unless !cache[:cache].nil? && cache[:endpoints_to_cache].include?(args[0])
+    return super(*args) unless !cache[:cache].nil? && cache[:endpoints_to_cache]&.include?(args[0])
 
     cache_filtered_name = cache_name_filter(args[1], cache[:ignored_headers])
 
@@ -20,7 +20,7 @@ module CacheAspect
   private
 
   def cache_name_filter(client_data, ignored_headers)
-    filtered_headers = client_data[:headers].filter { |key, _value| !ignored_headers.include?(key) }
+    filtered_headers = client_data[:headers].filter { |key, _value| !ignored_headers&.include?(key) }
     [{ body: client_data[:body], params: client_data[:params], headers: filtered_headers }].to_s.to_sym
   end
 end

data/lib/macaw_framework/core/server.rb

@@ -2,6 +2,7 @@
 
 require_relative "../middlewares/rate_limiter_middleware"
 require_relative "../data_filters/response_data_filter"
+require_relative "../middlewares/memory_invalidation_middleware"
 require_relative "../errors/too_many_requests_error"
 require_relative "../aspects/prometheus_aspect"
 require_relative "../aspects/logging_aspect"
@@ -24,7 +25,7 @@ class Server
   # @param {Integer} port
   # @param {String} bind
   # @param {Integer} num_threads
-  # @param {CachingMiddleware} cache
+  # @param {MemoryInvalidationMiddleware} cache
   # @param {Prometheus::Client:Registry} prometheus
   # @return {Server}
   def initialize(macaw, endpoints_to_cache = nil, cache = nil, prometheus = nil, prometheus_mw = nil)
@@ -34,8 +35,8 @@ class Server
     @macaw_log = macaw.macaw_log
     @num_threads = macaw.threads
     @work_queue = Queue.new
-    ignored_headers = set_rate_limiting
-    set_ssl
+    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 }
@@ -86,11 +87,12 @@ class Server
     raise EndpointNotMappedError unless @macaw.respond_to?(method_name)
     raise TooManyRequestsError unless @rate_limit.nil? || @rate_limit.allow?(client.peeraddr[3])
 
+    declare_client_session(client)
     client_data = get_client_data(body, headers, parameters)
 
     @macaw_log.info("Running #{path.gsub("\n", "").gsub("\r", "")}")
     message, status, response_headers = call_endpoint(@prometheus_middleware, @macaw_log, @cache,
-                                                      method_name, client_data)
+                                                      method_name, client_data, client.peeraddr[3])
     status ||= 200
     message ||= nil
     response_headers ||= nil
@@ -106,13 +108,24 @@ class Server
     client.close
   end
 
+  def declare_client_session(client)
+    @session[client.peeraddr[3]] ||= [{}, Time.now]
+    @session[client.peeraddr[3]] = [{}, Time.now] if @session[client.peeraddr[3]][0].nil?
+  end
+
   def set_rate_limiting
-    if @macaw.config&.dig("macaw", "rate_limiting")
-      ignored_headers = @macaw.config["macaw"]["rate_limiting"]["ignore_headers"] || []
-      @rate_limit = RateLimiterMiddleware.new(
-        @macaw.config["macaw"]["rate_limiting"]["window"].to_i || 1,
-        @macaw.config["macaw"]["rate_limiting"]["max_requests"].to_i || 60
-      )
+    return unless @macaw.config&.dig("macaw", "rate_limiting")
+
+    @rate_limit = RateLimiterMiddleware.new(
+      @macaw.config["macaw"]["rate_limiting"]["window"].to_i || 1,
+      @macaw.config["macaw"]["rate_limiting"]["max_requests"].to_i || 60
+    )
+  end
+
+  def set_cache_ignored_h
+    ignored_headers = []
+    if @macaw.config&.dig("macaw", "cache", "ignored_headers")
+      ignored_headers = @macaw.config["macaw"]["cache"]["ignore_headers"] || []
     end
     ignored_headers
   end
@@ -131,10 +144,31 @@ class Server
     raise e
   end
 
-  def call_endpoint(name, client_data)
+  def set_session
+    @session = {}
+    inv = if @macaw.config&.dig("macaw", "session", "invalidation_time")
+            MemoryInvalidationMiddleware.new(@macaw.config["macaw"]["session"]["invalidation_time"])
+          else
+            MemoryInvalidationMiddleware.new
+          end
+    inv.cache = @session
+  end
+
+  def set_features
+    set_rate_limiting
+    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[:parameters] }
+      {
+        headers: client_data[:headers],
+        body: client_data[:body],
+        params: client_data[:parameters],
+        client: @session[client_ip][0]
+      }
     )
   end
 

data/lib/macaw_framework/middlewares/{caching_middleware.rb → memory_invalidation_middleware.rb}

@@ -3,7 +3,7 @@
 ##
 # Middleware responsible for storing and
 # invalidating cache.
-class CachingMiddleware
+class MemoryInvalidationMiddleware
   attr_accessor :cache, :mutex
 
   def initialize(inv_time_seconds = 3_600)

data/lib/macaw_framework/version.rb

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

data/lib/macaw_framework.rb

@@ -3,7 +3,7 @@
 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/caching_middleware"
+require_relative "macaw_framework/middlewares/memory_invalidation_middleware"
 require_relative "macaw_framework/core/server"
 require_relative "macaw_framework/version"
 require "prometheus/client"
@@ -31,7 +31,7 @@ module MacawFramework
         @bind = @config["macaw"]["bind"] || "localhost"
         @threads = @config["macaw"]["threads"] || 5
         unless @config["macaw"]["cache"].nil?
-          @cache = CachingMiddleware.new(@config["macaw"]["cache"]["cache_invalidation"].to_i || 3_600)
+          @cache = MemoryInvalidationMiddleware.new(@config["macaw"]["cache"]["cache_invalidation"].to_i || 3_600)
         end
         @prometheus = Prometheus::Client::Registry.new if @config["macaw"]["prometheus"]
         @prometheus_middleware = PrometheusMiddleware.new if @config["macaw"]["prometheus"]

data/sig/{caching_middleware.rbs → memory_invalidation_middleware.rbs}

@@ -1,4 +1,4 @@
-class CachingMiddleware
+class MemoryInvalidationMiddleware
   @cache: Hash[String, Array[string]]
 
   attr_accessor cache: Hash[String, Array[string]]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: macaw_framework
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Aria Diniz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-04-28 00:00:00.000000000 Z
+date: 2023-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prometheus-client
@@ -24,7 +24,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.1'
-description: A project started for study purpose that I intend to keep working on.
+description: |-
+  A lightweight web framework designed for building efficient backend applications. Initially
+  created for study purposes, now production-ready and open for contributions.
 email:
 - aria.diniz.dev@gmail.com
 executables: []
@@ -38,6 +40,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - lib/macaw_framework.rb
 - lib/macaw_framework/aspects/cache_aspect.rb
 - lib/macaw_framework/aspects/logging_aspect.rb
@@ -47,17 +50,17 @@ files:
 - lib/macaw_framework/data_filters/response_data_filter.rb
 - lib/macaw_framework/errors/endpoint_not_mapped_error.rb
 - lib/macaw_framework/errors/too_many_requests_error.rb
-- lib/macaw_framework/middlewares/caching_middleware.rb
+- lib/macaw_framework/middlewares/memory_invalidation_middleware.rb
 - lib/macaw_framework/middlewares/prometheus_middleware.rb
 - lib/macaw_framework/middlewares/rate_limiter_middleware.rb
 - lib/macaw_framework/utils/http_status_code.rb
 - lib/macaw_framework/version.rb
 - macaw_logo.png
-- sig/caching_middleware.rbs
 - sig/http_status_code.rbs
 - sig/logging_aspect.rbs
 - sig/macaw_framework.rbs
 - sig/macaw_framework/macaw.rbs
+- sig/memory_invalidation_middleware.rbs
 - sig/request_data_filtering.rbs
 - sig/server.rbs
 homepage: https://github.com/ariasdiniz/macaw_framework
@@ -85,5 +88,5 @@ requirements: []
 rubygems_version: 3.4.12
 signing_key: 
 specification_version: 4
-summary: A web framework still in development.
+summary: A lightweight back-end web framework
 test_files: []