guaraci 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 872f02c23c21487409ca93acc9c6fb36fd25d54f8a03f0c6ffe502f9b36e61a6
-  data.tar.gz: 42e120be9876e28afdec28d8673287d927d8a9a4fbff3011fec36ccd08c98b84
+  metadata.gz: 68c9e80fa2a0485fef35d157487369ecb47a9768d70e09d68245b99866a20e84
+  data.tar.gz: e63b52cdab47b82f80f741cbef4bc0b75615ca4c2054c6f47dc2e935df5ae783
 SHA512:
-  metadata.gz: b8c423cb5d52ebd4420ca37959bd0b0e147b238ddc2882e5145664b29059cc10fdf5908f61e8928500ceb94707873aaba1d9d6aa7779a433e32f70d3f948152c
-  data.tar.gz: d9404e2dd3929e1b2c950f37412b495a9a0d61b77801c33de8b4b3e718aa72561b8b100dd49f49f472fed908d32cc3fba7ebacb8770a178e740efcd5a5d3258b
+  metadata.gz: 3eba3b02f82c5391b76644cde67d36790f3865e2643356cd0f6bcd2132e143fec02908319c98ed5c469673f207dd9bcdd923bc3795eefc0af702ac9e1c2e2188
+  data.tar.gz: 48521a8e90e75fade5e384d879c9ecf5d7f6c1242c8ef176fead81eee7e583bda0cf020ff833fa5b8bf2c804c5857debb96fe833afe7fbe78b0794d912d43f77

data/README.md

@@ -1,39 +1,168 @@
-# Guaraci
+# ☀️ Guaraci
 
-TODO: Delete this and the text below, and describe your gem
+[![Static Badge](https://img.shields.io/badge/rubygems-guaraci-brightgreen)](https://rubygems.org/gems/guaraci)
+[![Gem Version](https://badge.fury.io/rb/guaraci.svg)](https://badge.fury.io/rb/guaraci)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/guaraci`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.4.0-red.svg)](https://ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Guaraci is very a simple Ruby web microframework built on top of the powerful [Async::HTTP](https://github.com/socketry/async-http).
+It was designed to be minimalist, providing a clean and intuitive API with as little overhead as possible.
+
+Its goal is to be minimalist, with a small codebase focused on simplicity, without the need to learn extensive DSLs like other frameworks; it only requires plain Ruby.
+
+## Features
+
+- **High performance** - Powered by Async::HTTP for non-blocking concurrency
+- **Flexible** - Easy to extend and customize
+- **Lightweight** - Few dependencies
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+In your gemfiile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'guaraci'
+```
+
+And run:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install guaraci
+```
+
+## How to use
+
+### Hello World
+
+```ruby
+require 'guaraci'
+
+Guaraci::Server.run(port: 3000) do |request|
+  response = Guaraci::Response.ok
+  response.json({ message: "Hello, World!" })
+  response.render
+end
+```
+
+### Routing
+A little about routing first: I decided to keep the code simple, so no routing dsl and constructors were built. Why? The ideia is to use plain ruby, without the need to learn another DSL apart ruby itself, like rails, sinatra, roda, etc.
+
+I REALLY recommend you to use the new pattern matching feature that comes with Ruby 3.x by default.
+
+```ruby
+require 'guaraci'
+
+Guaraci::Server.run(host: 'localhost', port: 8000) do |request|
+  case [request.method, request.path_segments]
+  in ['GET', []]
+    handle_api_request(request)
+  in ['GET', ['health']]
+    health_check
+  else
+    not_found
+  end
+end
+
+def handle_api_request(request)
+  response = Guaraci::Response.ok
+  response.json({
+    method: request.method,
+    path: request.path_segments,
+    params: request.params,
+    timestamp: Time.now.iso8601
+  })
+  response.render
+
+##  Or you can pass a block like this
+#
+#   Guaraci::Response.ok do |res|
+#     res.json({
+#       method: request.method,
+#       path: request.path_segments,
+#       params: request.params,
+#       timestamp: Time.now.iso8601
+#      })
+#   end.to_a
+end
+
+def health_check
+  response = Guaraci::Response.ok
+  response.json({ status: 'healthy', uptime: Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+  response.render
+
+## Or you can pass a block like this
+#
+#   Guaraci::Response.ok do |res|
+#     res.json({
+#       status: 'healthy',
+#       uptime: Process.clock_gettime(Process::CLOCK_MONOTONIC)
+#     })
+#   end
+end
+
+def not_found
+  response = Guaraci::Response.new(404)
+  response.json({ error: 'Not Found' })
+  response.render
+end
+
 ```
 
-## Usage
+## Examples
 
-TODO: Write usage instructions here
+You can see more examples on how to build guaraci apps inside [Examples](https://github.com/glmsilva/guaraci/tree/main/examples) folder
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Clone the repository:
+
+1. Execute `bin/setup` to install dependencies
+2. Execute `rake test` to run tests
+3. Execute `bin/console` for an interactive prompt
+
+### Tests
+Its the plain and old minitest :)
+
+```bash
+rake test
+
+ruby test/guaraci/test_request.rb
+
+bundle exec rubocop
+```
+
+## Inspiration
+### Why this name?
+
+In **Tupi-Guarani** indigenous culture, Guaraci (_Guaracy_ or _Kûarasy_) is the solar deity associated with the origin of life. As a central figure in indigenous mythology, and son of **Tupã**, Guaraci embodies the power of the sun, is credited with giving rise to all living beings, and protector of the hunters.
+
+Its also a word that can be translated to "Sun" in Tupi-Guarani language.
+
+## Roadmap
+
+- [ ] Integrated pipeline Middleware
+- [ ] Templates support
+- [ ] WebSocket support
+- [ ] Streaming responses
+- [ ] A better documentation
+- [ ] More examples on how to use it
+- [ ] Performance benchmark
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Acknowledgements
 
-## Contributing
+- [Async::HTTP](https://github.com/socketry/async-http) - The powerful asynchronous base of this project
+- [Wisp](https://github.com/gleam-wisp/wisp) - The great framework that I enjoyed using so much and that inspired the philosophy behind building this one
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/guaraci.
+## 📄 License
+ [MIT License](https://opensource.org/licenses/MIT).
 
-## License
+---
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Thank you so much, feel free to contact me ☀️ [Guilherme Silva](https://github.com/glmsilva)

data/lib/guaraci/request.rb

@@ -1,41 +1,186 @@
-# frozen_string_literal
+# frozen_string_literal: true
 
-require 'json'
+require "json"
 
 module Guaraci
+  # Represents the requests wrapper that provides convenient access to request data.
+  # This class wraps the HTTP request object from Async::HTTP.
+  # @example Basic request information
+  #   request.method        #=> "GET"
+  #   request.path_segments #=> ["api", "users", "123"]
+  #   request.headers       #=> Protocol::HTTP::Headers instance
+  #
+  # @example Accessing request data
+  #   request.params       #=> {"name" => "John", "email" => "john@example.com"}
+  #   request.query_params #=> [["sort", "name"], ["order", "asc"]]
+  #
+  # @see https://github.com/socketry/async-http Async::HTTP documentation
+  # @author Guilherme Silva
+  # @since 1.0.0
   class Request
-    attr_reader :method, :path_segments, :raw_request
+    # The HTTP method for this request.
+    #
+    # Common methods include GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.
+    # The method is automatically extracted from the underlying request object
+    # and normalized to uppercase string format.
+    #
+    # @return [String] HTTP method in uppercase (e.g., "GET", "POST")
+    # @example
+    #   request.method #=> "GET"
+    attr_reader :method
 
+    # The path segments extracted from the request URL.
+    #
+    # The path is automatically split by "/" and empty segments are removed.
+    # This creates an array that's perfect for pattern matching and routing logic.
+    # Leading and trailing slashes are ignored.
+    #
+    # @return [Array<String>] Path segments without empty strings
+    # @example Path segments
+    #   # For URL: /api/users/123/profile
+    #   request.path_segments #=> ["api", "users", "123", "profile"]
+    #   user_id = request.path_segments[2]  #=> "123"
+    #
+    # @example Pattern Matching for Routing (Recommended)
+    #   # Using Ruby's pattern matching for elegant routing
+    #   case [request.method, request.path_segments]
+    #   in ['GET', ['api', 'users', user_id]]
+    #     # user_id automatically captured from URL
+    #   in ['GET', ['api', 'posts', post_id, 'comments']]
+    #     # post_id automatically captured from URL
+    #   end
+    attr_reader :path_segments
+
+    # The original request object from the HTTP server.
+    #
+    # This provides access to the underlying request implementation when you need
+    # low-level access to request data that isn't exposed through the wrapper methods.
+    # Use this when you need to access protocol-specific features.
+    #
+    # @return [Object] The original request object from Async::HTTP
+    # @see https://github.com/socketry/async-http/blob/main/lib/async/http/protocol/request.rb
+    # @example
+    #   request.raw_request.version #=> "HTTP/1.1"
+    #   request.raw_request.scheme  #=> "http"
+    attr_reader :raw_request
+
+    # Initialize a new request wrapper.
+    #
+    # Creates a new Request instance that wraps the underlying HTTP request object.
+    # Automatically extracts commonly needed information like HTTP method and path segments
+    # for easy access and pattern matching.
+    #
+    # @param raw_request [Object] The original request object from Async::HTTP
+    # @example
+    #   # Usually called internally by the server
+    #   request = Guaraci::Request.new(async_http_request)
     def initialize(raw_request)
       @method = raw_request.method
-      @path_segments = raw_request.path.split('/').reject(&:empty?)
+      @path_segments = raw_request.path&.split("/")&.reject(&:empty?)
       @raw_request = raw_request
     end
 
+    # Read and return the request body content.
+    # Returns nil if the request has no body content.
+    #
+    # @return [String, nil] The complete request body as a string
+    # @example
+    #   request.body #=> '{"name":"John","email":"john@example.com"}'
+    # @example For requests without body
+    #   request.body #=> nil
     def body
-      @body ||= raw_request.read
+      @body ||= raw_request&.read
     end
 
+    # Parse the request body as JSON and return the resulting object.
+    #
+    # Attempts to parse the request body as JSON using {JSON.parse}.
+    # If the body is not valid JSON or is empty, returns an empty hash instead
+    # of raising an exception. This makes it safe to call even when you're not
+    # sure if the request contains JSON data.
+    #
+    # @return [Hash] Parsed JSON data, or empty hash if parsing fails
+    # @see JSON.parse
+    # @example Successful parsing
+    #   # Request body: '{"name":"John","age":30}'
+    #   request.params #=> {"name" => "John", "age" => 30}
+    #
+    # @example Invalid JSON handling
+    #   # Request body: 'invalid json'
+    #   request.params #=> {}
+    #
+    # @example Empty body handling
+    #   # Request body: nil
+    #   request.params #=> {}
     def params
       JSON.parse(body)
-    rescue JSON::ParseError
+    rescue JSON::ParserError
       {}
     end
 
+    # Access the request headers.
+    #
+    # @return [Protocol::HTTP::Headers] The request headers collection
+    # @see https://github.com/socketry/protocol-http/blob/main/lib/protocol/http/headers.rb Protocol::HTTP::Headers
+    # All headers are accessed in lowercase strings according to Protocol::HTTP::Headers
+    # So that way, "User-Agent" becomes "user-agent"
+    # @example
+    #   request.headers['content-type']   #=> 'application/json'
+    #   request.headers['authorization']  #=> 'Bearer token123'
+    #   request.headers['user-agent']     #=> 'Mozilla/5.0...'
     def headers = raw_request.headers
 
+    # Extract the query string from the request URL.
+    #
+    # Returns the complete query string portion of the URL (everything after the "?").
+    # If no query string is present, returns an empty string. The query string is
+    # returned as-is without any URL decoding.
+    #
+    # @return [String] The query string or empty string if none present
+    # @example
+    #   # For URL: /users?name=john&age=30&active=true
+    #   request.query #=> "name=john&age=30&active=true"
+    #
+    # @example No query string
+    #   # For URL: /users
+    #   request.query #=> ""
     def query
-      raw_request.query || ""
+      raw_request&.query || ""
     end
 
+    # Parse the query string into key-value pairs.
+    #
+    # Splits the query string into an array of [key, value] pairs for easy processing.
+    # Each parameter is split on the "=" character. Parameters without values will
+    # have the value portion as an empty string or nil. The result is cached for
+    # subsequent calls.
+    #
+    # @return [Array<Array<String>>] Array of [key, value] pairs
+    # @example
+    #   # For query: "name=john&age=30&active=true"
+    #   request.query_params #=> [["name", "john"], ["age", "30"], ["active", "true"]]
+    #
+    # @example Parameters without values
+    #   # For query: "debug&verbose=1&flag"
+    #   request.query_params #=> [["debug"], ["verbose", "1"], ["flag"]]
+    #
+    # @example No query string
+    #   request.query_params #=> []
     def query_params
       @query_params ||= parse_query
     end
 
     private
 
+    # Split the query string into key-value pairs.
+    #
+    # Internal method that handles the actual parsing of the query string.
+    # Splits on "&" to separate parameters, then splits each parameter on "="
+    # to separate keys from values.
+    #
+    # @return [Array<Array<String>>] Parsed query parameters
     def parse_query
-      query.split('&').map { |q| q.split('=') }.to_a
+      query&.split("&")&.map { |q| q.split("=") }.to_a
     end
   end
 end

data/lib/guaraci/response.rb

@@ -1,30 +1,226 @@
 # frozen_string_literal: true
 
-require 'json'
+require "json"
+require "protocol/http"
 
 module Guaraci
+  # HTTP response builder for the Guaraci web framework.
+  #
+  # It handles the conversion between high-level Ruby objects and the low-level Protocol::HTTP
+  # objects required by the HTTP server.
+  #
+  # @example Basic JSON response
+  #   response = Guaraci::Response.ok do |res|
+  #     res.json({ message: "Hello World", status: "success" })
+  #   end
+  #   response.render #=> Protocol::HTTP::Response
+  #
+  # @example HTML response with custom status
+  #   response = Guaraci::Response.new(201) do |res|
+  #     res.html("<h1>Resource Created</h1>")
+  #   end
+  #   response.render
+  #
+  # @example Plain text response
+  #   response = Guaraci::Response.ok do |res|
+  #     res.text("Simple message")
+  #   end
+  #   response.render
+  #
+  # @see https://github.com/socketry/protocol-http Protocol::HTTP documentation
+  # @see https://github.com/socketry/async-http Async::HTTP documentation
+  # @author Guilherme SIlva
+  # @since 1.0.0
   class Response
-    attr_reader :status, :body, :headers
+    # The HTTP status code for this response.
+    #
+    # Common status codes:
+    # - 200: OK (successful request)
+    # - 201: Created (resource created successfully)
+    # - 400: Bad Request (client error)
+    # - 404: Not Found (resource not found)
+    # - 500: Internal Server Error (server error)
+    #
+    # @return [Integer] HTTP status code (e.g., 200, 404, 500)
+    # @see https://tools.ietf.org/html/rfc7231#section-6 HTTP status code definitions
+    # @example
+    #   response.status #=> 200
+    attr_reader :status
 
+    # The HTTP response body containing the actual content.
+    #
+    # The body is automatically converted to {Protocol::HTTP::Body::Buffered}
+    # format when content is written using {#write}, {#json}, {#html}, or {#text}.
+    # This ensures compatibility with Async::HTTP's streaming requirements.
+    #
+    # @return [Protocol::HTTP::Body::Buffered] HTTP response body
+    # @see https://github.com/socketry/protocol-http/blob/main/lib/protocol/http/body/buffered.rb Protocol::HTTP::Body::Buffered
+    # @example
+    #   response.body.read #=> '{"message":"Hello World"}'
+    attr_reader :body
+
+    # The HTTP response headers collection.
+    #
+    # Headers are stored as {Protocol::HTTP::Headers} objects
+    #
+    # @return [Protocol::HTTP::Headers] HTTP response headers
+    # @see https://github.com/socketry/protocol-http/blob/main/lib/protocol/http/headers.rb Protocol::HTTP::Headers
+    # @example
+    #   response.headers['content-type'] #=> 'application/json'
+    #   response.headers['content-length'] #=> '25'
+    attr_reader :headers
+
+    # Initialize a new HTTP response with the specified status code.
+    #
+    # Creates a new response instance with empty headers and body.
+    # The headers are initialized as {Protocol::HTTP::Headers} and the
+    # body starts as an empty buffered body until content is written.
+    #
+    # @param status [Integer] HTTP status code
+    # @raise [ArgumentError] if status is not a valid HTTP status code
+    #
+    # @example Creating different response types
+    #   success = Guaraci::Response.new(200)    # OK
+    #   not_found = Guaraci::Response.new(404)  # Not Found
+    #   error = Guaraci::Response.new(500)      # Internal Server Error
+    #
+    # @example With content
+    #   response = Guaraci::Response.new(201)
+    #   response.json({ id: 123, created: true })
     def initialize(status)
       @status = status
-      @headers = {}
-      @body = []
+      @headers = Protocol::HTTP::Headers.new
+      @body = default_body
     end
 
+    # Create a successful HTTP response (200 OK).
+    #
+    # This is a convenient factory method for creating successful responses.
+    # It automatically sets the status to 200 and yields the response instance
+    # to the provided block for content configuration.
+    #
+    # @yield [response] Block to configure the response content and headers
+    # @yieldparam response [Response] The response instance to configure
+    # @return [Response] The configured response instance with status 200
+    #
+    # @example Without block (empty 200 response)
+    #   response = Guaraci::Response.ok
+    #   response.status #=> 200
+    #
+    # @example With configuration block
+    #   response = Guaraci::Response.ok do |res|
+    #     res.json({ message: "Operation successful!" })
+    #   end
+    #
+    # @example Method chaining after creation
+    #   response = Guaraci::Response.ok
+    #   response.json({ data: [1, 2, 3] })
     def self.ok
       res = new(200)
       yield(res) if block_given?
       res
     end
 
-    def json(object)
-      @headers["Content-Type"] = "application/json"
-      @body = [JSON.dump((object))]
+    # Write content to the response body with specified content type.
+    #
+    # This is the base method used by all other content methods (json, html, text).
+    # It automatically converts the content to {Protocol::HTTP::Body::Buffered} format
+    # required by Async::HTTP and sets the appropriate Content-Type header.
+    #
+    # @param content [String, Array] Content to write to response body
+    # @param content_type [String] MIME type for the response
+    # @return [Response] Self for method chaining
+    #
+    # @see Protocol::HTTP::Body::Buffered
+    def write(content, content_type: "application/json")
+      @headers["content-type"] = content_type
+      @body = Protocol::HTTP::Body::Buffered.wrap(content)
+      self
+    end
+
+    # Write JSON content to the response body.
+    #
+    # Automatically serializes the provided object to JSON using {JSON.dump}
+    #
+    # @param content [Object] Any object that can be serialized to JSON
+    # @return [Response] Self for method chaining
+    #
+    # @example Hash object
+    #   response.json({ message: "Hello", data: [1, 2, 3] })
+    def json(content)
+      write(JSON.dump(content))
+    end
+
+    # Write HTML content to the response body.
+    #
+    # Sets the Content-Type to "text/html" and writes the provided HTML string.
+    # No HTML validation or processing is performed - the content is sent as-is.
+    #
+    # @param content [String] HTML content
+    # @return [Response] Self for method chaining
+    #
+    # @example Simple HTML
+    #   response.html("<h1>Welcome</h1>")
+    #
+    # @example Complete HTML document
+    #   response.html(<<~HTML)
+    #     <!DOCTYPE html>
+    #     <html>
+    #       <head><title>My Page</title></head>
+    #       <body><h1>Hello World!</h1></body>
+    #     </html>
+    #   HTML
+    def html(content)
+      write(content, content_type: "text/html")
     end
 
-    def to_a
-      [@status, @headers, @body]
+    # Write plain text content to the response body.
+    #
+    # Sets the Content-Type to "text/plain" and writes the provided text.
+    #
+    # @param content [String] Plain text content
+    # @return [Response] Self for method chaining
+    #
+    # @example Simple text
+    #   response.text("Hello, World!")
+    #
+    # @example Multi-line text
+    #   response.text("Line 1\nLine 2\nLine 3")
+    def text(content)
+      write(content, content_type: "text/plain")
+    end
+
+    # Convert the response to a Protocol::HTTP::Response object.
+    #
+    # This method transforms the Guaraci::Response into the low-level response format
+    # required by the Async::HTTP server. It ensures that all components (status, headers, body)
+    # are properly formatted for HTTP transmission.
+    #
+    # The returned object contains:
+    # - version: HTTP version (automatically determined by Protocol::HTTP)
+    # - status: Integer HTTP status code
+    # - headers: Protocol::HTTP::Headers instance with all response headers
+    # - body: Protocol::HTTP::Body::Buffered instance containing the response content
+    #
+    # @return [Protocol::HTTP::Response] A complete HTTP response object ready for transmission
+    # @see https://github.com/socketry/protocol-http/blob/main/lib/protocol/http/response.rb Protocol::HTTP::Response
+    # @see https://github.com/socketry/async-http Async::HTTP server documentation
+    #
+    # @example Basic usage
+    #   response = Guaraci::Response.ok { |r| r.json({message: "Hello"}) }
+    #   http_response = response.render
+    #   http_response.status #=> 200
+    #   http_response.headers['content-type'] #=> 'application/json'
+    def render
+      Protocol::HTTP::Response.new(nil, @status, @headers, @body)
+    end
+
+    private
+
+    # @return [Protocol::HTTP::Body::Buffered] An empty body
+    # @see Protocol::HTTP::Body::Buffered.wrap
+    def default_body
+      Protocol::HTTP::Body::Buffered.wrap("")
     end
   end
-end
+end

data/lib/guaraci/server.rb

@@ -1,25 +1,90 @@
 # frozen_string_literal: true
 
-require_relative './request.rb'
+require_relative "./request"
 require "async"
 require "async/http/server"
 require "async/http/endpoint"
 require "async/http/protocol/http1"
-require "json"
 
 module Guaraci
+  # HTTP server that handles incoming requests with a simple block-based API.
+  # Built on top of Async::HTTP for high performance and non-blocking I/O.
+  #
+  # @example Basic server
+  #   Guaraci::Server.run do |request|
+  #     Guaraci::Response.ok { |r| r.json({message: "Hello World"}) }.render
+  #   end
+  #
+  # @example Pattern Matching Routing (What I recommend)
+  #   Guaraci::Server.run do |request|
+  #     case [request.method, request.path_segments]
+  #     in ['GET', []]
+  #       Guaraci::Response.ok { |r| r.html("<h1>Welcome!</h1>") }.render
+  #     in ['GET', ['health']]
+  #       Guaraci::Response.ok { |r| r.json({ status: "healthy" }) }.render
+  #     in ['GET', ['api', 'users']]
+  #       Guaraci::Response.ok { |r| r.json({ users: [] }) }.render
+  #     in ['GET', ['api', 'users', user_id]]
+  #       Guaraci::Response.ok { |r| r.json({ user: { id: user_id } }) }.render
+  #     in ['POST', ['api', 'users']]
+  #       user_data = request.params
+  #       Guaraci::Response.new(201) { |r| r.json({ created: user_data }) }.render
+  #     else
+  #       Guaraci::Response.new(404) { |r| r.json({ error: "Not Found" }) }.render
+  #     end
+  #   end
+  #
+  # @author Guilherme Silva
+  # @since 1.0.0
+  # @see Guaraci::Request
+  # @see Guaraci::Response
+  # @see https://github.com/socketry/async-http Async::HTTP documentation
   class Server
+    # Creates a new server instance with the given handler block.
+    #
+    # @param block [Proc] The request handler block that will be called for each HTTP request
+    # @yield [request] Block to handle incoming HTTP requests
+    # @yieldparam request [Guaraci::Request] The wrapped HTTP request object
+    # @yieldreturn [Protocol::HTTP::Response] Response object from calling .render on a Guaraci::Response
+    #
+    # @example
+    #   server = Guaraci::Server.new do |request|
+    #     case request.method
+    #     when "GET"
+    #       Guaraci::Response.ok { |r| r.text("Hello World") }.render
+    #     else
+    #       Guaraci::Response.new(405) { |r| r.text("Method Not Allowed") }.render
+    #     end
+    #   end
     def initialize(&block)
       @handler = block
     end
 
+    # Process an incoming HTTP request.
+    #
+    # This method is called by the Async::HTTP server for each incoming request.
+    # It wraps the raw request in a {Guaraci::Request} object and executes the
+    # configured handler block.
+    #
+    # @param request [Object] Raw HTTP request from Async::HTTP
+    # @return [Protocol::HTTP::Response] The response object returned by the handler
+    #
+    # @note This method is typically called internally by the server infrastructure
+    #   and not directly by user code.
+    # @see https://github.com/socketry/async-http/blob/main/lib/async/http/server.rb Async::HTTP::Server
     def call(request)
       request = Request.new(request)
 
       instance_exec(request, &@handler)
     end
 
-    def self.run(host: 'localhost', port: 8000, &block)
+    # Starts an HTTP server on the specified host and port.
+    # The server runs indefinitely until stopped.
+    #
+    # @param host [String] the host to bind to
+    # @param port [Integer] the port to listen on
+    # @param block [Proc] the request handler block
+    def self.run(host: "localhost", port: 8000, &block)
       app = new(&block)
       url = "http://#{host}:#{port}"
 

data/lib/guaraci/version.rb

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

data/lib/guaraci.rb

@@ -3,6 +3,30 @@
 require_relative "./guaraci/server"
 require_relative "./guaraci/response"
 require_relative "./guaraci/request"
+require_relative "./guaraci/version"
 
+# # Guaraci is a minimalist Ruby web framework built on Async::HTTP.
+# It provides a simple, clean API for building web applications without
+# complex DSLs or extensive configuration.
+#
+# The framework embraces plain Ruby patterns and encourages the use of
+# pattern matching for routing, making it perfect for modern Ruby applications.
+#
+# @example Basic application
+#   require 'guaraci'
+#
+#   Guaraci::Server.run do |request|
+#     case [request.method, request.path_segments]
+#     in ['GET', []]
+#       Guaraci::Response.ok { |r| r.html("<h1>Welcome to Guaraci!</h1>") }.render
+#     in ['GET', ['api', 'health']]
+#       Guaraci::Response.ok { |r| r.json({status: "ok", timestamp: Time.now}) }.render
+#     else
+#       Guaraci::Response.new(404) { |r| r.json({error: "Not found"}) }.render
+#     end
+#   end
+#
+# @author Guilherme Silva
+# @version 1.0.0
 module Guaraci
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: guaraci
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Guilherme Silva
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A very simple web framework made with async http
 email:
 - guilherme.gss@outlook.com.br