webtransport_handler behaviour (webtransport v0.3.1)

WebTransport handler behaviour.

Applications implement this behaviour to handle WebTransport sessions. The callbacks are invoked by the session process when events occur.

Example Handler

Prefer init/3 — it receives the handler_opts map from the connection / listener options, which is the only way to plumb things like an owner pid, a request-id, or application configuration into the handler. The 2-arity init/2 is kept only as a back-compat shim and is called when the handler does not export init/3.

  -module(my_wt_handler).
  -behaviour(webtransport_handler).
 
  -export([init/3, handle_stream/4, handle_datagram/2,
           handle_stream_closed/3, terminate/2]).
 
  init(Session, _Req, Opts) ->
      Owner = maps:get(owner, Opts, undefined),
      {ok, #{session => Session, owner => Owner}}.
 
  handle_stream(Stream, Type, Data, State) ->
      {ok, State, [{send, Stream, <<"echo: ", Data/binary>>}]}.
 
  handle_datagram(Data, State) ->
      {ok, State}.
 
  handle_stream_closed(_Stream, _Reason, State) ->
      {ok, State}.
 
  terminate(_Reason, _State) ->
      ok.

Summary

Types

action/0

Callbacks

handle_action_failed/3

handle_datagram/2

handle_info/2

handle_stream/4

handle_stream_closed/3

handle_stream_fin/4

init/2

init/3

origin_check/2

terminate/2

Types

action/0

-type action() ::
          {send, webtransport:stream(), iodata()} |
          {send, webtransport:stream(), iodata(), fin} |
          {send_datagram, iodata()} |
          {open_stream, bidi | uni} |
          {close_stream, webtransport:stream()} |
          {reset_stream, webtransport:stream(), non_neg_integer()} |
          {stop_sending, webtransport:stream(), non_neg_integer()} |
          drain_session |
          {close_session, non_neg_integer(), binary()}.

Callbacks

handle_action_failed/3

(optional)

-callback handle_action_failed(Action, Reason, State) -> Result
                                  when
                                      Action :: action(),
                                      Reason :: term(),
                                      State :: term(),
                                      Result :: {ok, NewState} | {stop, StopReason, NewState},
                                      NewState :: term(),
                                      StopReason :: term().

handle_datagram/2

-callback handle_datagram(Data, State) -> Result
                             when
                                 Data :: binary(),
                                 State :: term(),
                                 Result ::
                                     {ok, NewState} | {ok, NewState, Actions} | {stop, Reason, NewState},
                                 NewState :: term(),
                                 Actions :: [action()],
                                 Reason :: term().

handle_info/2

(optional)

-callback handle_info(Info, State) -> Result
                         when
                             Info :: term(),
                             State :: term(),
                             Result :: {ok, NewState} | {ok, NewState, Actions} | {stop, Reason, NewState},
                             NewState :: term(),
                             Actions :: [action()],
                             Reason :: term().

handle_stream/4

-callback handle_stream(Stream, Type, Data, State) -> Result
                           when
                               Stream :: webtransport:stream(),
                               Type :: bidi | uni,
                               Data :: binary(),
                               State :: term(),
                               Result :: {ok, NewState} | {ok, NewState, Actions} | {stop, Reason, NewState},
                               NewState :: term(),
                               Actions :: [action()],
                               Reason :: term().

handle_stream_closed/3

-callback handle_stream_closed(Stream, Reason, State) -> Result
                                  when
                                      Stream :: webtransport:stream(),
                                      Reason :: normal | {reset, non_neg_integer()} | {error, term()},
                                      State :: term(),
                                      Result :: {ok, NewState} | {stop, Reason, NewState},
                                      NewState :: term().

handle_stream_fin/4

(optional)

-callback handle_stream_fin(Stream, Type, Data, State) -> Result
                               when
                                   Stream :: webtransport:stream(),
                                   Type :: bidi | uni,
                                   Data :: binary(),
                                   State :: term(),
                                   Result ::
                                       {ok, NewState} | {ok, NewState, Actions} | {stop, Reason, NewState},
                                   NewState :: term(),
                                   Actions :: [action()],
                                   Reason :: term().

init/2

(optional)

-callback init(Session, Req) -> {ok, State} | {ok, State, Actions} | {error, Reason}
                  when
                      Session :: webtransport:session(),
                      Req :: webtransport:request(),
                      State :: term(),
                      Actions :: [action()],
                      Reason :: term().

init/3

(optional)

-callback init(Session, Req, Opts) -> {ok, State} | {ok, State, Actions} | {error, Reason}
                  when
                      Session :: webtransport:session(),
                      Req :: webtransport:request(),
                      Opts :: map(),
                      State :: term(),
                      Actions :: [action()],
                      Reason :: term().

origin_check/2

(optional)

-callback origin_check(Headers, Opts) -> Result
                          when
                              Headers :: [{binary(), binary()}],
                              Opts :: map(),
                              Result :: accept | {reject, Status :: 400..599, Reason :: binary()}.

terminate/2

-callback terminate(Reason, State) -> term()
                       when Reason :: normal | {error, term()} | term(), State :: term().