Http handler

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
primitive AuthFailed
  """
  HTTP failure reason for when SSL Authentication failed.

  This failure reason is only reported to HTTP client HTTPHandler instances.
  """

primitive ConnectionClosed
  """
  HTTP failure reason for when the connection was closed
  either from the other side (detectable when using TCP keepalive)
  or locally (e.g. due to an error).
  """
primitive ConnectFailed
  """
  HTTP failure reason for when a connection could not be established.

  This failure reason is only valid for HTTP client HTTPHandlers.
  """

type HTTPFailureReason is (
  AuthFailed |
  ConnectionClosed |
  ConnectFailed
  )
  """
  HTTP failure reason reported to `HTTPHandler.failed()`.
  """

interface HTTPHandler
  """
  This is the interface through which HTTP messages are delivered *to*
  application code. On the server, this will be HTTP Requests (GET,
  HEAD, DELETE, POST, etc) sent from a client. On the client, this will
  be the HTTP Responses coming back from the server. The protocol is largely
  symmetrical and the same interface definition is used, though what
  processing happens behind the interface will of course vary.

  This interface delivers asynchronous events when receiving an HTTP
  message (called a `Payload`). Calls to these methods are made in
  the context of the `HTTPSession` actor so most of them should be
  passing data on to a processing actor.

  Each `HTTPSession` must have a unique instance of the handler. The
  application code does not necessarily know when an `HTTPSession` is created,
  so the application must provide an instance of `HandlerFactory` that
  will be called at the appropriate time.
  """
  fun ref apply(payload: Payload val): Any =>
    """
    Notification of an incoming message. On the client, these will
    be responses coming from the server. On the server these will be requests
    coming from the client. The `Payload` object carries HTTP headers
    and the method, URL, and status codes.

    Only one HTTP message will be processed at a time, and that starts
    with a call to this method. This would be a good time to create
    an actor to deal with subsequent information pertaining to this
    message.
    """

  fun ref chunk(data: ByteSeq val) =>
    """
    Notification of incoming body data. The body belongs to the most
    recent `Payload` delivered by an `apply` notification.
    """

  fun ref finished() =>
    """
    Notification that no more body chunks are coming. Delivery of this HTTP
    message is complete.
    """

  fun ref cancelled() =>
    """
    Notification that transferring the payload has been cancelled locally,
    e.g. by disposing the client, closing the server or manually cancelling a single request.
    """

  fun ref failed(reason: HTTPFailureReason) =>
    """
    Notification about failure to transfer the payload
    (e.g. connection could not be established, authentication failed, connection was closed prematurely, ...)
    """

  fun ref throttled() =>
    """
    Notification that the session temporarily can not accept more data.
    """

  fun ref unthrottled() =>
    """
    Notification that the session can resume accepting data.
    """

  fun ref need_body() =>
    """
    Notification that the HTTPSession is ready for Stream or Chunked
    body data.
    """

interface HandlerFactory
  """
  The TCP connections that underlie HTTP sessions get created within
  the `http` package at times that the application code can not
  predict. Yet, the application code has to provide custom hooks into
  these connections as they are created. To accomplish this, the
  application code provides an instance of a `class` that implements
  this interface.

  The `HandlerFactory.apply` method will be called when a new
  `HTTPSession` is created, giving the application a chance to create
  an instance of its own `HTTPHandler`. This happens on both
  client and server ends.
  """

  fun apply(session: HTTPSession): HTTPHandler ref^
    """
    Called by the `HTTPSession` when it needs a new instance of the
    application's `HTTPHandler`. It is suggested that the
    `session` value be passed to the constructor for the new
    `HTTPHandler` so that it is available for making
    `throttle` and `unthrottle` calls.
    """