Handler

Callbacks

init/2

Check out the following example

@impl Requiem
def init(conn, client) do

  Logger.debug("new connection is established, connection_id: #{conn.dcid}")

  if client.origin == "my-origin.example.com" do

    my_state = %{path: client.path}
    {:ok, conn, state}

  else

    {:stop, 400, :forbidden}

  end
end

It has a role similar to GenServer.init/2, and is called after a successful QUIC handshake.

Arguments

There are two arguments, ConnectionState and ClientIndication.

If necessary, you can check the values of the ClientIndication parameters, origin and path, and do whatever you want. In the example above, if the origin is not correct, the connection is disconnected at this point, and if the origin is as expected, the connection is maintained.

If WebTransport mode is turned off, the client indication variable will be passed as nil. See the WebTransport mode page for details.

The handling of origin is similar to that of CORS in HTTP.

path is the part of the URL path specified when this server is accessed.

If the URL is quic-transport://my-service.example.org/foobar, then the /foobar part will be included.

You may want to look at this value to see if you can branch the service if necessary.

Return value

If there are no problems, return a value like {:ok, conn, state}. It is the same as GenServer.init/1 in that you can freely create and return a state. The only difference is that the ConnectionState structure is passed around as well.

If there is a problem and you want to shut down the connection here, it will return data of the form {:stop, error_code, reason}.

The error_code and reason used here will be used in the CLOSE FRAME to be sent to the client.

  @callback init(conn :: Requiem.ConnectionState.t(), client :: Requiem.ClientIndication.t()) ::
              {:ok, Requiem.ConnectionState.t(), any}
              | {:ok, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:stop, non_neg_integer, atom}

---

handle_info/3

This one is also somewhat understandable if you look at the example.

@impl Requiem
def handle_info({:my_event, my_param}, conn, state) do
   do_something(my_param)
  {:noreply, conn, state}
end

You can think of it as almost the same as GenServer.handle_info/2, except that it pulls around the ConnectionState structure for the arguments and return value. This callback is called when the process receives a message.

  @callback handle_info(
              request :: term,
              conn :: Requiem.ConnectionState.t(),
              state :: any
            ) ::
              {:noreply, Requiem.ConnectionState.t(), any}
              | {:noreply, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:stop, non_neg_integer, atom}

---

handle_cast/3

As with handle_info/2 above, you can think of this function as having almost the same role as the corresponding GenServer.handle_cast/2.

@impl Requiem
def handle_cast({:my_event, my_param}, conn, state) do
   do_something(my_param)
  {:noreply, conn, state}
end

  @callback handle_cast(
              request :: term,
              conn :: Requiem.ConnectionState.t(),
              state :: any
            ) ::
              {:noreply, Requiem.ConnectionState.t(), any}
              | {:noreply, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:stop, non_neg_integer, atom}

---

handle_call/4

@impl Requiem
def handle_call({:my_event, my_param}, from, conn, state) do
  {:reply, conn, state}
end

This is also the same as handle_info/2 and handle_cast/2 above.

  @callback handle_call(
              request :: term,
              from :: pid,
              conn :: Requiem.ConnectionState.t(),
              state :: any
            ) ::
              {:noreply, Requiem.ConnectionState.t(), any}
              | {:noreply, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:reply, any, Requiem.ConnectionState.t(), any}
              | {:reply, any, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:stop, non_neg_integer, atom}

---

terminate/3

Similarly, there is a function called terminate/3.

@impl Requiem
def terminate(reason, conn, state) do
  :ok
end

  @type terminate_reason :: :normal | :shutdown | {:shutdown, term} | term

  @callback terminate(
              reason :: terminate_reason,
              conn :: Requiem.ConnectionState.t(),
              state :: any
            ) :: any

---

handle_stream/4

A function that can process data received in a stream.

@impl Requiem
def handle_stream(stream_id, data, conn, state) do

  case do_something(stream_id, data) do
    {:ok, good_result} -> {:ok, conn, state}
    {:error, :bad_result} -> {:stop, 400, :bad_request}
  end

end

Arguments

You may be familiar with conn and state by now. The stream_id and data specified in the first two arguments are passed.

Return value

If there is no problem, return data in the form of {:ok, conn, state}. If there is a problem and you want to close the connection, return data in the form of {:stop, error_code, reason}.

  @callback handle_stream(
              stream_id :: non_neg_integer,
              data :: binary,
              conn :: Requiem.ConnectionState.t(),
              state :: any
            ) ::
              {:ok, Requiem.ConnectionState.t(), any}
              | {:ok, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:stop, non_neg_integer, atom}

---

handle_dgram/3

It can handle data sent as datagrams. It is the same as handle_stream/4 except that there is no such thing as a stream_id.

@impl Requiem
def handle_dgram(data, conn, state) do

  case do_something(stream_id, data) do
    {:ok, good_result} -> {:ok, conn, state}
    {:error, :bad_result} -> {:stop, 400, :bad_request}
  end

end

The config of enable_dgram must be set.

See Configuration for details.

  @callback handle_dgram(
              data :: binary,
              conn :: Requiem.ConnectionState.t(),
              state :: any
            ) ::
              {:ok, Requiem.ConnectionState.t(), any}
              | {:ok, Requiem.ConnectionState.t(), any, timeout | :hibernate}
              | {:stop, non_neg_integer, atom}

---

Methods

The following functions are available in your handler.

close/0

It is possible to disconnect by returning {:stop, error_code, reason} in the return value of each callback. However, there may be times when you want to disconnect in an asynchronous process other than the callback timing.

In such a case, call this close function.

---

close/2

There is also a version of close where error_code and reason can be passed. The above version is treated as a normal close, but this version can express an application error.

close(error_code, reason)

---

stream_send/2

Use this when you want to send data to a client through a stream.

stream_send(stream_id, data)

You can use it this way, but be careful about the value of stream_id.

See Stream for details.

---

dgram_send/1

This can be used when you want to send a datagram instead of a stream.

The config of enable_dgram must be set.

See Configuration for details.

dgram_send(data)

---

ConnectionState

The actual state of the conn passed in each callback is a structure defined in the Requiem.ConnectionState module.

It has the following fields

• conn.scid
• conn.dcid
• conn.odcid

These are the connection IDs used in the QUIC frame, and are the ones specified when the connection is initiated. odcid is what was specified before validation by token using the retry frame.

It also has the address of the peer.

• conn.address

This is the structure of the Requiem.Address module.

• conn.address.host
• conn.address.port

In this way, you can access information about the other party's connection.

---

ClientIndication

ConnectionState以外にも知っておかなければならないものが一つあります。 init/2の第二引数として渡されるClientIndicationです。

@impl Requiem
def init(conn, client) do
  my_state = %{}
  {:ok, conn, my_state}
end

これは、WebTransportモードのときだけ利用されます。 WebTransportモードではない場合はここにはnilが渡されます。 (WebTransportモードについて詳しくは、ConfigurationやWebTransportを参照してください。)

WebTransportモードの場合は、クライアントからstream_idが2のstreamを通して受け取ったデータを自動的にパースし、init/2に渡します。

ここで、originやpathの値をチェックして、問題があれば切断することが出来ます。

@impl Requiem
def init(conn, client) do
  if client.origin == "example.org"  do
    my_state = %{path: client.path}
    {:ok, conn, my_state}
  else
    {:stop, 400, :shutdown}
  end
end