cowboy_stream.erl 2.5 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253
  1. %% Copyright (c) 2015, Loïc Hoguin <essen@ninenines.eu>
  2. %%
  3. %% Permission to use, copy, modify, and/or distribute this software for any
  4. %% purpose with or without fee is hereby granted, provided that the above
  5. %% copyright notice and this permission notice appear in all copies.
  6. %%
  7. %% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8. %% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9. %% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  10. %% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  11. %% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  12. %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  13. %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  14. -module(cowboy_stream).
  15. -type streamid() :: any().
  16. -type fin() :: fin | nofin.
  17. -type headers() :: map(). %% @todo cowboy:http_headers() when they're maps
  18. -type status_code() :: 100..999. %% @todo cowboy:http_status() when not binary
  19. -type state() :: any().
  20. -type commands() :: [{response, fin(), status_code(), headers()}
  21. | {data, fin(), iodata()}
  22. | {promise, binary(), binary(), binary(), binary(), headers()}
  23. | {flow, auto | integer()}
  24. | {spawn, pid()}
  25. | {upgrade, module(), state()}].
  26. -type human_reason() :: atom().
  27. -type reason() :: [{internal_error, timeout | {error | exit | throw, any()}, human_reason()}
  28. | {socket_error, closed | atom(), human_reason()}
  29. | {stream_error, cow_http2:error_reason(), human_reason()}
  30. | {connection_error, cow_http2:error_reason(), human_reason()}
  31. | {stop, cow_http2:frame(), human_reason()}].
  32. -callback init(streamid(), fin(), binary(), binary(), binary(), binary(),
  33. headers(), cowboy:opts()) -> {commands(), state()}.
  34. -callback data(streamid(), fin(), binary(), State) -> {commands(), State} when State::state().
  35. -callback info(streamid(), any(), state()) -> {commands(), State} when State::state().
  36. -callback terminate(streamid(), reason(), state()) -> any().
  37. %% @todo To optimize the number of active timers we could have a command
  38. %% that enables a timeout that is called in the absence of any other call,
  39. %% similar to what gen_server does. However the nice thing about this is
  40. %% that the connection process can keep a single timer around (the same
  41. %% one that would be used to detect half-closed sockets) and use this
  42. %% timer and other events to trigger the timeout in streams at their
  43. %% intended time.
  44. %%
  45. %% This same timer can be used to try and send PING frames to help detect
  46. %% that the connection is indeed unresponsive.