Class: Guaraci::Server

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

Overview

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.

Examples:

Basic server

Guaraci::Server.run do |request|
  Guaraci::Response.ok { |r| r.json({message: "Hello World"}) }.render
end

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

See Also:

Author:

  • Guilherme Silva

Since:

  • 1.0.0

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(&block) {|request| ... } ⇒ Server

Creates a new server instance with the given handler block.

Examples:

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

Parameters:

  • block (Proc) —

    The request handler block that will be called for each HTTP request

Yields:

  • (request) —

    Block to handle incoming HTTP requests

Yield Parameters:

Yield Returns:

  • (Protocol::HTTP::Response) —

    Response object from calling .render on a Guaraci::Response

Since:

  • 1.0.0



59
60
61
 
# File 'lib/guaraci/server.rb', line 59

def initialize(&block)
  @handler = block
end

Class Method Details

.run(host: "localhost", port: 8000, &block) ⇒ Object

Starts an HTTP server on the specified host and port. The server runs indefinitely until stopped.

Parameters:

  • host (String) (defaults to: "localhost") —

    the host to bind to

  • port (Integer) (defaults to: 8000) —

    the port to listen on

  • block (Proc) —

    the request handler block

Since:

  • 1.0.0



87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/guaraci/server.rb', line 87

def self.run(host: "localhost", port: 8000, &block)
  app = new(&block)
  url = "http://#{host}:#{port}"

  Async do
    endpoint = Async::HTTP::Endpoint.parse(url)
    server = Async::HTTP::Server.new(app.method(:call), endpoint, protocol: Async::HTTP::Protocol::HTTP1)

    puts "Guaraci running on #{url}"
    server.run
  end
end

Instance Method Details

#call(request) ⇒ Protocol::HTTP::Response

Note:

This method is typically called internally by the server infrastructure and not directly by user code.

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 Request object and executes the configured handler block.

Parameters:

  • request (Object) —

    Raw HTTP request from Async::HTTP

Returns:

  • (Protocol::HTTP::Response) —

    The response object returned by the handler

See Also:

Since:

  • 1.0.0



75
76
77
78
79
 
# File 'lib/guaraci/server.rb', line 75

def call(request)
  request = Request.new(request)

  instance_exec(request, &@handler)
end