Class: Guaraci::Request

Inherits:
Object
  • Object
show all
Defined in:
lib/guaraci/request.rb

Overview

Represents the requests wrapper that provides convenient access to request data. This class wraps the HTTP request object from Async::HTTP.

Examples:

Basic request information

request.method        #=> "GET"
request.path_segments #=> ["api", "users", "123"]
request.headers       #=> Protocol::HTTP::Headers instance

Accessing request data

request.params       #=> {"name" => "John", "email" => "[email protected]"}
request.query_params #=> [["sort", "name"], ["order", "asc"]]

See Also:

Author:

  • Guilherme Silva

Since:

  • 1.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(raw_request) ⇒ 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.

Examples:

# Usually called internally by the server
request = Guaraci::Request.new(async_http_request)

Parameters:

  • raw_request (Object) —

    The original request object from Async::HTTP

Since:

  • 1.0.0



77
78
79
80
81
 
# File 'lib/guaraci/request.rb', line 77

def initialize(raw_request)
  @method = raw_request.method
  @path_segments = raw_request.path&.split("/")&.reject(&:empty?)
  @raw_request = raw_request
end

Instance Attribute Details

#method ⇒ String (readonly)

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.

Examples:

request.method #=> "GET"

Returns:

  • (String) —

    HTTP method in uppercase (e.g., “GET”, “POST”)

Since:

  • 1.0.0



30
31
32
 
# File 'lib/guaraci/request.rb', line 30

def method
  @method
end

#path_segments ⇒ Array<String> (readonly)

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.

Examples:

Path segments

# For URL: /api/users/123/profile
request.path_segments #=> ["api", "users", "123", "profile"]
user_id = request.path_segments[2]  #=> "123"

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

Returns:

  • (Array<String>) —

    Path segments without empty strings

Since:

  • 1.0.0



52
53
54
 
# File 'lib/guaraci/request.rb', line 52

def path_segments
  @path_segments
end

#raw_request ⇒ Object (readonly)

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.

Examples:

request.raw_request.version #=> "HTTP/1.1"
request.raw_request.scheme  #=> "http"

Returns:

  • (Object) —

    The original request object from Async::HTTP

See Also:

Since:

  • 1.0.0



65
66
67
 
# File 'lib/guaraci/request.rb', line 65

def raw_request
  @raw_request
end

Instance Method Details

#body ⇒ String?

Read and return the request body content. Returns nil if the request has no body content.

Examples:

request.body #=> '{"name":"John","email":"[email protected]"}'

For requests without body

request.body #=> nil

Returns:

  • (String, nil) —

    The complete request body as a string

Since:

  • 1.0.0



91
92
93
 
# File 'lib/guaraci/request.rb', line 91

def body
  @body ||= raw_request&.read
end

#headers ⇒ Protocol::HTTP::Headers

Access the request headers.

All headers are accessed in lowercase strings according to Protocol::HTTP::Headers So that way, “User-Agent” becomes “user-agent”

Examples:

request.headers['content-type']   #=> 'application/json'
request.headers['authorization']  #=> 'Bearer token123'
request.headers['user-agent']     #=> 'Mozilla/5.0...'

Returns:

  • (Protocol::HTTP::Headers) —

    The request headers collection

See Also:

Since:

  • 1.0.0



131
 
# File 'lib/guaraci/request.rb', line 131

def headers = raw_request.headers

#params ⇒ Hash

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.

Examples:

Successful parsing

# Request body: '{"name":"John","age":30}'
request.params #=> {"name" => "John", "age" => 30}

Invalid JSON handling

# Request body: 'invalid json'
request.params #=> {}

Empty body handling

# Request body: nil
request.params #=> {}

Returns:

  • (Hash) —

    Parsed JSON data, or empty hash if parsing fails

See Also:

  • JSON.parse

Since:

  • 1.0.0



115
116
117
118
119
 
# File 'lib/guaraci/request.rb', line 115

def params
  JSON.parse(body)
rescue JSON::ParserError
  {}
end

#query ⇒ String

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.

Examples:

# For URL: /users?name=john&age=30&active=true
request.query #=> "name=john&age=30&active=true"

No query string

# For URL: /users
request.query #=> ""

Returns:

  • (String) —

    The query string or empty string if none present

Since:

  • 1.0.0



147
148
149
 
# File 'lib/guaraci/request.rb', line 147

def query
  raw_request&.query || ""
end

#query_params ⇒ Array<Array<String>>

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.

Examples:

# For query: "name=john&age=30&active=true"
request.query_params #=> [["name", "john"], ["age", "30"], ["active", "true"]]

Parameters without values

# For query: "debug&verbose=1&flag"
request.query_params #=> [["debug"], ["verbose", "1"], ["flag"]]

No query string

request.query_params #=> []

Returns:

  • (Array<Array<String>>) —

    Array of [key, value] pairs

Since:

  • 1.0.0



169
170
171
 
# File 'lib/guaraci/request.rb', line 169

def query_params
  @query_params ||= parse_query
end