class HTTP::Server

• HTTP::Server
• Reference
• Object

Overview

An HTTP server.

A server is given a handler that receives an HTTP::Server::Context that holds the HTTP::Request to process and must in turn configure and write to an HTTP::Server::Response.

The HTTP::Server::Response object has status and headers properties that can be configured before writing the response body. Once response output is written, changing the status and headers properties has no effect.

The HTTP::Server::Response is also a write-only IO, so all IO methods are available in it.

The handler given to a server can simply be a block that receives an HTTP::Server::Context, or it can be an HTTP::Handler. An HTTP::Handler has an optional next handler, so handlers can be chained. For example, an initial handler may handle exceptions in a subsequent handler and return a 500 status code (see HTTP::ErrorHandler), the next handler might log the incoming request (see HTTP::LogHandler), and the final handler deals with routing and application logic.

Simple Setup

A handler is given with a block.

require "http/server"

server = HTTP::Server.new do |context|
  context.response.content_type = "text/plain"
  context.response.print "Hello world!"
end

server.bind 8080
puts "Listening on http://127.0.0.1:8080"
server.listen

With non-localhost bind address

require "http/server"

server = HTTP::Server.new do |context|
  context.response.content_type = "text/plain"
  context.response.print "Hello world!"
end

server.bind "0.0.0.0", 8080
puts "Listening on http://0.0.0.0:8080"
server.listen

Add handlers

A series of handlers are chained.

require "http/server"

server = HTTP::Server.new([
  HTTP::ErrorHandler.new,
  HTTP::LogHandler.new,
  HTTP::CompressHandler.new,
  HTTP::StaticFileHandler.new("."),
])

server.bind "127.0.0.1", 8080
server.listen

Add handlers and block

A series of handlers is chained, the last one being the given block.

require "http/server"

server = HTTP::Server.new([
  HTTP::ErrorHandler.new,
  HTTP::LogHandler.new,
]) do |context|
  context.response.content_type = "text/plain"
  context.response.print "Hello world!"
end

server.bind "0.0.0.0", 8080
server.listen

Defined in:

Constructors

• .new(handlers : Array(HTTP::Handler), &handler : HTTP::Handler::Proc) : self

  Creates a new HTTP server with a handler chain constructed from the handlers array and the given block.

• .new(&handler : HTTP::Handler::Proc) : self

  Creates a new HTTP server with the given block as handler.

• .new(handlers : Array(HTTP::Handler)) : self

  Creates a new HTTP server with the handlers array as handler chain.

• .new(handler : HTTP::Handler | HTTP::Handler::Proc)

  Creates a new HTTP server with the given handler.

Class Method Summary

• .build_middleware(handlers, last_handler : Context -> ? = nil)

  Builds all handlers as the middleware for HTTP::Server.

Instance Method Summary

• #addresses : Array(Socket::Address)
• #bind(socket : Socket::Server) : Nil

  Adds a Socket::Server socket to this server.

• #bind_tcp(host : String, port : Int32, reuse_port : Bool = false) : Socket::IPAddress

  Creates a TCPServer listenting on host:port and adds it as a socket, returning the local address and port the server listens on.

• #bind_tcp(port : Int32, reuse_port : Bool = false) : Socket::IPAddress

  Creates a TCPServer listenting on 127.0.0.1:port and adds it as a socket, returning the local address and port the server listens on.

• #bind_unix(path : String) : Socket::UNIXAddress

  Creates a UNIXServer bound to path and adds it as a socket.

• #bind_unused_port(host : String = "127.0.0.1", reuse_port : Bool = false) : Socket::IPAddress

  Creates a TCPServer listening on an unused port and adds it as a socket.

• #close

  Gracefully terminates the server.

• #closed? : Bool

  Returns true if this server is closed.

• #each_address(&block : Socket::Address -> )

  Enumerates all addresses this server is bound to.

• #listen(port : Int32, reuse_port : Bool = false)

  Creates a TCPServer listenting on 127.0.0.1:port, adds it as a socket and starts the server.

• #listen(host : String, port : Int32, reuse_port : Bool = false)

  Creates a TCPServer listenting on host:port, adds it as a socket and starts the server.

• #listen

  Starts the server.

• #listening? : Bool

  Returns true if this server is listening on it's sockets.

• #tls : OpenSSL::SSL::Context::Server?
• #tls=(tls : OpenSSL::SSL::Context::Server?)

Constructor Detail

Class Method Detail

Instance Method Detail

server = HTTP::Server.new { }
server.bind_unix "/tmp/my-socket.sock"

server = HTTP::Server.new { }
server.bind_unused_port # => Socket::IPAddress.new("127.0.0.1", 12345)