macaw_framework 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b35cc5b2fba0adc8ded0f76db41699323cc3957d54382d19e554d0e3dc77f51
-  data.tar.gz: bcd983f6afe8b8864b5d2c012c120ead8290b521ed66f49477f8defb7eed2ede
+  metadata.gz: 6e3d33329ff53ab220c857c255d70b687d50f0703054ecef2866a17676867eed
+  data.tar.gz: 2c340f529123646d86a261630f2bcb5bb89dbbfda10a65f4820f1db8ece73504
 SHA512:
-  metadata.gz: 9a7f7ef95d76e906b706a036d8cb299ba1b5e3be607ba8cdc13da216b11665b019635bca062ac83fc3067a18ab36148df12d3af2bdbc0fbe42fa3a8e0cb2c018
-  data.tar.gz: 56a97dff9ddac5f4142b82d441de3264d4044ace0f8f9496a2e0f49a8e384c6cf57ed705bcf68dd051c536b0dc4e4b9a643161f6563a7bcfe095f2b6f691e5ff
+  metadata.gz: 79abf5fdf0729ef0464245c8765c88516b5445bff3123160e8f84fe1e43fa5360f311fceb731cb9f2823c49ac0caac5a78e3f35812ef3fe5e38cec2ab373cd81
+  data.tar.gz: db3b2bec7d0999497c752d9d1664d2bd99e0b35bb1bd67f95d5e529c7a46950ae62a02334f65016b4a947373a4a3871d5aa75832f33765e930dc7c0c4367dd45

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -41,3 +41,15 @@
 - 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
+
+## [1.0.2] - 2023-05-06
+
+- Fixing a bug with cache where ignored_headers where not being properly loaded
+- Fixed a bug with cache where URL parameters were not being considered in the strategy
+- Updating SECURITY.md with more information

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,59 @@ 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!
+
+```
 
-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:
+### Caching: Improve performance by caching responses and configuring cache invalidation
+
+```ruby
+m.get('/cached_data', cache: true) do |context|
+# Retrieve data
+end
+```
+
+Observation: To activate caching you also have to set it's properties on the application.json file. If you don't, caching strategy will not work.
+See section below for configurations.
+
+### Session management: Handle user sessions securely with server-side in-memory storage
+
+```ruby
+m.get('/login') do |context|
+  # Authenticate user
+  context[:client][:user_id] = user_id
+end
+
+m.get('/dashboard') do |context|
+  # Check if the user is logged in
+  if context[:client][: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 +86,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,27 @@
+# Security Policy
+
+## Supported Versions
+
+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:                |
+
+## Reporting a Vulnerability
+
+We encourage responsible disclosure of security vulnerabilities. If you find a vulnerability in MacawFramework, please follow the steps below:
+
+1. Open an issue on the [GitHub repository](https://github.com/ariasdiniz/macaw_framework/issues) describing the vulnerability. Please include as much detail as possible, such as the affected version, the steps to reproduce the issue, and the potential impact of the vulnerability.
+
+Alternatively, you can send an email to aria.diniz.dev@gmail.com with the same information.
+
+2. We will review and acknowledge the report within a reasonable time frame. We may ask for additional information or guidance to help us understand and reproduce the issue.
+
+3. We will work on addressing the vulnerability and will provide updates on the progress.
+
+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/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,15 +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
-      )
-    end
-    ignored_headers
+    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
+    return unless @macaw.config&.dig("macaw", "cache", "ignore_headers")
+
+    @macaw.config["macaw"]["cache"]["ignore_headers"] || []
   end
 
   def set_ssl
@@ -131,14 +142,35 @@ 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[:params],
+        client: @session[client_ip][0]
+      }
     )
   end
 
   def get_client_data(body, headers, parameters)
-    { body: body, headers: headers, parameters: parameters }
+    { body: body, headers: headers, params: parameters }
   end
 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.2"
 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/main/CODEOWNERS

@@ -0,0 +1 @@
+*       @ariasdiniz

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.2
 platform: ruby
 authors:
 - Aria Diniz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-04-28 00:00:00.000000000 Z
+date: 2023-05-07 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,18 @@ 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
+- main/CODEOWNERS
 - 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 +89,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: []