This is Elixir framework for running WebTransport (over http/3) server.
This library depends on cloudflare/quiche.
quiche is written in Rust, so you need to prepare Rust compiler to build this library.
At this time, quiche does not support WebTransport, so a forked and edited version is used.
ReQUIem requires Rustler to bridge between elixir and rust.
This library is currently in an experimental phase.
We plan to ensure its stability by conducting sufficient interoperability and performance tests in the future.
If available in Hex, the package can be installed
by adding requiem to your list of dependencies in mix.exs:
def deps do
[
{:requiem, "~> 0.4.3"}
]
endDocumentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/requiem.
Prepare a server and set up DNS so that you can access the server with your domain name.
Also, prepare the certificate chain and private key pem file to be used for that domain name.
You can follow the same procedure as when dealing with TLS on a typical web server.
Also, decide the port to use this time, and set the firewall etc. so that you can access the server via that port.
First of all, let's define your own handler.
Write the use Requiem line as follows.
lib/my_app/my_handler.ex
defmodule MyApp.MyHandler do
use Requiem, otp_app: :my_app
endPrepare the config file.
In config/config.exs or config/releases.exs,
Write as follows.
Make sure that the certificate can be specified via an environment variable.
import Config
config :my_app, MyApp.MyHandler,
host: "0.0,0.0",
port: 443,
cert_chain: System.get_env("CERT_FILE"),
priv_key: System.get_env("PRIV_KEY"),
initial_max_data: 10_000_000,
max_udp_payload_size: 1350,
initial_max_stream_data_bidi_local: 1_000_000,
initial_max_stream_data_bidi_remote: 1_000_000,
initial_max_stream_data_uni: 1_000_000,
initial_max_streams_uni: 10,
initial_max_streams_bidi: 10,
disable_active_migration: true,
enable_early_data: true,Set it like this. There are many more parameters for config, but I won't explain them here. See Configuration for details.
When you start the application, include the handler module that you just created in the child_spec definition of Supervisor.
lib/my_app/application.ex
defmodule MyApp do
use Application
def start(_type, _args) do
[
# ...,
MyApp.MyHandler
]
|> Supervisor.start_link([
strategy: :one_for_one,
name: MyApp.Supervisor
])
end
endNow let's launch the application.
CERT_FILE=/path/to/cert PRIV_KEY=/path/to/priv_key mix run --no-haltIf there are no problems with the config and other settings, this will start the application, but it is of no use at this point. The reason is that no callback is written in the Handler.
Let's try to implement just printing the sent data to the standard output.
lib/my_app/my_handler.ex
defmodule MyApp.MyHandler do
use Requiem, otp_app: :my_app
@impl Requiem
def handle_stream(_stream_id, data, conn, state) do
IO.puts(data)
{:ok, conn, state}
end
endIf you want to create an echo server that sends data directly back to the recipient, you can write the following
defmodule MyApp.MyHandler do
use Requiem, otp_app: :my_app
@impl Requiem
def handle_stream(stream_id, data, conn, state) do
stream_send(stream_id, data, false)
{:ok, conn, state}
end
endHowever, this implementation may fail depending on the value of stream_id. See Stream for details.
Let's add a few more things.
defmodule MyApp.MyHandler do
use Requiem, otp_app: :my_app
@impl Requiem
def init(conn, request) do
# XXX you can validate this request with following params
# request.authority
# request.path
# request.origin
{:ok, conn, %{}}
end
@impl Requiem
def handle_stream(stream_id, data, conn, state) do
stream_send(stream_id, data, false)
{:ok, conn, state}
end
@impl Requiem
def handle_info(request, conn, state) do
{:noreply, conn, state}
end
@impl Requiem
def handle_cast(request, conn, state) do
{:noreply, conn, state}
end
@impl Requiem
def handle_call(request, from, conn, state) do
{:reply, :ok, conn, state}
end
@impl Requiem
def terminate(_reason, _conn, _state) do
:ok
end
endIf you are familiar with GenServer, you will see familiar names in the list. There are some parameters that you may not have seen before, such as conn and request, but other than that, you can probably guess how it behaves.
You can hook initialization and termination processes with init/2 and terminate/3, and receive inter-process messages with handle_info/3, handle_cast/3, and handle_call/4.
In addition, handle_dgram/3 can handle received datagrams. To send a datagram, use dgram_send/1.
defmodule MyApp.MyHandler do
use Requiem, otp_app: :my_app
@impl Requiem
def init(conn, request) do
{:ok, conn, %{}}
end
@impl Requiem
def handle_stream(stream_id, data, conn, state) do
stream_send(stream_id, data, false)
{:ok, conn, state}
end
@impl Requiem
def handle_dgram(data, conn, state) do
dgram_send(data)
{:ok, conn, state}
end
@impl Requiem
def handle_info(request, conn, state) do
{:noreply, conn, state}
end
@impl Requiem
def handle_cast(request, conn, state) do
{:noreply, conn, state}
end
@impl Requiem
def handle_call(request, from, conn, state) do
{:reply, :ok, conn, state}
end
@impl Requiem
def terminate(_reason, _conn, _state) do
:ok
end
endOnce you have done this, you can open the WebTransport example page in Google Chrome and try to interact with it.
For more information on the various callbacks and the various functions that can be called from here, see Handler.
This repository contains an example project that can be used as a reference.
Check inside the examples directory.
https://github.com/xflagstudio/requiem/wiki/Handler
https://github.com/xflagstudio/requiem/wiki/Configuration
MIT-LICENSE
Copyright (C) 2021, XFLAG Studio (mixi, Inc.)
See LICENCE for details.
- Lyo Kato <lyo.kato at gmail.com>
- Hidetaka Kojo <hidetaka.kojo at gmail.com>