tcp_connection_notify.pony

interface TCPConnectionNotify
  """
  Notifications for TCP connections.

  For an example of using this class please see the documentation for the
  `TCPConnection` and `TCPListener` actors.
  """
  fun ref accepted(conn: TCPConnection ref) =>
    """
    Called when a TCPConnection is accepted by a TCPListener.
    """
    None

  fun ref proxy_via(host: String, service: String): (String, String) =>
    """
    Called before before attempting to connect to the destination server
    In order to connect via proxy, return the host & service for the proxy
    server.

    An implementation of this function might look like:
    ```pony
    let _proxy_host = "some-proxy.example.com"
    let _proxy_service = "80"
    var _destination_host: ( None | String )
    var _destination_service: ( None | String )

    fun ref proxy_via(host: String, service: String): (String, String) =>
      _destination_host = host
      _destination_service = service
      ( _proxy_host, _proxy_service )
    ```
    """
    (host, service)

  fun ref connecting(conn: TCPConnection ref, count: U32) =>
    """
    Called if name resolution succeeded for a TCPConnection and we are now
    waiting for a connection to the server to succeed. The count is the number
    of connections we're trying. The notifier will be informed each time the
    count changes, until a connection is made or connect_failed() is called.
    """
    None

  fun ref connected(conn: TCPConnection ref) =>
    """
    Called when we have successfully connected to the server.
    """
    None

  fun ref connect_failed(conn: TCPConnection ref)
    """
    Called when we have failed to connect to all possible addresses for the
    server. At this point, the connection will never be established.

    It is expected to implement proper error handling. You need to opt in to
    ignoring errors, which can be implemented like this:

    ```pony
    fun ref connect_failed(conn: TCPConnection ref) =>
      None
    ```
    """

  fun ref auth_failed(conn: TCPConnection ref) =>
    """
    A raw TCPConnection has no authentication mechanism. However, when
    protocols are wrapped in other protocols, this can be used to report an
    authentication failure in a lower level protocol (e.g. SSL).
    """
    None

  fun ref sent(conn: TCPConnection ref, data: ByteSeq): ByteSeq =>
    """
    Called when data is sent on the connection. This gives the notifier an
    opportunity to modify sent data before it is written. To swallow data,
    return an empty string.
    """
    data

  fun ref sentv(conn: TCPConnection ref, data: ByteSeqIter): ByteSeqIter =>
    """
    Called when multiple chunks of data are sent to the connection in a single
    call. This gives the notifier an opportunity to modify the sent data chunks
    before they are written. To swallow the send, return an empty
    Array[String].
    """
    data

  fun ref received(
    conn: TCPConnection ref,
    data: Array[U8] iso,
    times: USize)
    : Bool
  =>
    """
    Called when new data is received on the connection. Return true if you
    want to continue receiving messages without yielding until you read
    max_size on the TCPConnection. Return false to cause the TCPConnection
    to yield now.

    Includes the number of times during the current behavior, that received has
    been called. This allows the notifier to end reads on a regular basis.
    """
    true

  fun ref expect(conn: TCPConnection ref, qty: USize): USize =>
    """
    Called when the connection has been told to expect a certain quantity of
    bytes. This allows nested notifiers to change the expected quantity, which
    allows a lower level protocol to handle any framing (e.g. SSL).
    """
    qty

  fun ref closed(conn: TCPConnection ref) =>
    """
    Called when the connection is closed.
    """
    None

  fun ref throttled(conn: TCPConnection ref) =>
    """
    Called when the connection starts experiencing TCP backpressure. You should
    respond to this by pausing additional calls to `write` and `writev` until
    you are informed that pressure has been released. Failure to respond to
    the `throttled` notification will result in outgoing data queuing in the
    connection and increasing memory usage.
    """
    None

  fun ref unthrottled(conn: TCPConnection ref) =>
    """
    Called when the connection stops experiencing TCP backpressure. Upon
    receiving this notification, you should feel free to start making calls to
    `write` and `writev` again.
    """
    None