raxx

RAXX

Interfaz para servidores web, marcos y clientes HTTP.

• Instalar desde hex.pm
• Documentación disponible en hexdoc
• Discuta en Slack

Consulte RAXX.KIT para un generador de proyectos que lo ayude a configurar un proyecto web basado en RAXX/ACE.

Servidor simple

1. Definición de un servidor

 defmodule MyServer do
  use Raxx.SimpleServer

  @ impl Raxx.SimpleServer
  def handle_request ( % { method: :GET , path: [ ] } , _state ) do
    response ( :ok )
    |> set_header ( "content-type" , "text/plain" )
    |> set_body ( "Hello, World!" )
  end

  def handle_request ( % { method: :GET , path: _ } , _state ) do
    response ( :not_found )
    |> set_header ( "content-type" , "text/plain" )
    |> set_body ( "Oops! Nothing here." )
  end
end

• La ruta de una solicitud se divide en segmentos. Una solicitud para GET / tiene ruta [] .

2. Ejecutar un servidor

Para iniciar un servidor RAXX, se necesita un servidor HTTP compatible. Este ejemplo usa ACE que puede servir tanto HTTP/1 como HTTP/2.

 raxx_server = { MyServer , nil }
http_options = [ port: 8080 , cleartext: true ]

{ :ok , pid } = Ace.HTTP.Service . start_link ( raxx_server , http_options )

• El segundo elemento en la tupla del servidor RAXX se pasa como el segundo argumento a la devolución de llamada handle_request/2 . En este ejemplo no se usa y, por lo tanto, se establece en nulo.

Comience su proyecto y visite http: // localhost: 8080.

Transmisión HTTP

Un intercambio HTTP implica un cliente que envía datos a un servidor que recibe una respuesta. Una vista simple es modelar esto como un solo mensaje enviado en cada dirección. Trabajar con este modelo corresponde a las devoluciones de llamada Raxx.SimpleServer .

           request -->
Client ============================================ Server
                                   <-- response

Cuando el modelo simple es insuficiente, RAXX expone un modelo inferior. Esto consiste en una serie de mensajes en cada dirección. Trabajar con este modelo corresponde a las devoluciones de llamada Raxx.Server .

           tail | data(1+) | head(request) -->
Client ============================================ Server
           <-- head(response) | data(1+) | tail

• El cuerpo de una solicitud o una respuesta es la combinación de todas las partes de datos enviadas.

Servidor con estado

El servidor LongPoll es con el estado. Después de recibir una solicitud completa, este servidor debe esperar una entrada adicional antes de enviar una respuesta al cliente.

 defmodule LongPoll do
  use Raxx.Server

  @ impl Raxx.Server
  def handle_head ( % { method: :GET , path: [ "slow" ] } , state ) do
    Process . send_after ( self ( ) , :reply , 30_000 )

    { [ ] , state }
  end

  @ impl Raxx.Server
  def handle_info ( :reply , _state ) do
    response ( :ok )
    |> set_header ( "content-type" , "text/plain" )
    |> set_body ( "Hello, Thanks for waiting." )
  end
end

• Un servidor de larga data necesita devolver dos cosas; las partes del mensaje para enviar, en este caso nada [] ; y el nuevo estado del servidor, en este caso no hay state de cambio.
• El initial_state está configurado cuando se inicia el servidor.

Transmisión de servidor

El servidor SubscribeToMessages transmite su respuesta. El servidor enviará el jefe de la respuesta al recibir la solicitud. Los datos se envían al cliente, como parte del cuerpo, cuando está disponible. La respuesta se completa cuando la sala de chat envía un :closed .

 defmodule SubscribeToMessages do
  use Raxx.Server

  @ impl Raxx.Server
  def handle_head ( % { method: :GET , path: [ "messages" ] } , state ) do
    { :ok , _ } = ChatRoom . join ( )
    outbound = response ( :ok )
    |> set_header ( "content-type" , "text/plain" )
    |> set_body ( true )

    { [ outbound ] , state }
  end

  @ impl Raxx.Server
  def handle_info ( { ChatRoom , :closed } , state ) do
    outbound = tail ( )

    { [ outbound ] , state }
  end

  def handle_info ( { ChatRoom , data } , state ) do
    outbound = data ( data )

    { [ outbound ] , state }
  end
end

• Usar set_body(true) marca que la respuesta tiene un cuerpo que aún no se conoce.
• Una transmisión debe tener una cola para completar, los metadatos agregados aquí se enviarán como remolques.

Transmisión de clientes

El servidor Upload escribe datos en un archivo tal como se recibe. Solo una vez que se ha recibido la solicitud completa, se envía una respuesta.

 defmodule Upload do
  use Raxx.Server

  @ impl Raxx.Server
  def handle_head ( % { method: :PUT , path: [ "upload" ] body: true } , _state ) do
    { :ok , io_device } = File . open ( "my/path" )
    { [ ] , { :file , device } }
  end

  @ impl Raxx.Server
  def handle_data ( data , state = { :file , device } ) do
    IO . write ( device , data )
    { [ ] , state }
  end

  @ impl Raxx.Server
  def handle_tail ( _trailers , state ) do
    response ( :see_other )
    |> set_header ( "location" , "/" )
  end
end

• Un cuerpo puede llegar dividido por paquetes, trozos o marcos. handle_data se invocará a medida que llegue cada parte. Una aplicación nunca debe asumir cómo un cuerpo se dividirá en piezas de datos.

Flujo de solicitud/respuesta

Vale la pena señalar qué garantías se dan en las piezas de solicitud pasadas a las funciones handle_* del servidor. Depende del tipo de servidor, Raxx.Server vs Raxx.SimpleServer :

Entonces, por ejemplo, después de un %Raxx.Request{body: false} se pasa a la devolución de llamada c:Raxx.Server.handle_head/2 de un servidor al servidor ( c:Raxx.Server.handle_info/2 Los mensajes podrían ser).

Del mismo modo, estas son las secuencias válidas de las partes de respuesta devueltas de los servidores:

Cualquier Raxx.Middleware s debe seguir la misma lógica.

Enrutador

El Raxx.Router se puede usar para hacer coincidir las solicitudes con módulos de servidor específicos.

 defmodule MyApp do
  use Raxx.Server

  use Raxx.Router , [
    { % { method: :GET , path: [ ] } , HomePage } ,
    { % { method: :GET , path: [ "slow" ] } , LongPoll } ,
    { % { method: :GET , path: [ "messages" ] } , SubscribeToMessages } ,
    { % { method: :PUT , path: [ "upload" ] } , Upload } ,
    { _ , NotFoundPage }
  ]
end