HTTPClientResponseDelegate

public protocol HTTPClientResponseDelegate : AnyObject

HTTPClientResponseDelegate allows an implementation to receive notifications about request processing and to control how response parts are processed. You can implement this protocol if you need fine-grained control over an HTTP request/response, for example, if you want to inspect the response headers before deciding whether to accept a response body, or if you want to stream your request body. Pass an instance of your conforming class to the HTTPClient.execute() method and this package will call each delegate method appropriately as the request takes place./

Backpressure

A HTTPClientResponseDelegate can be used to exert backpressure on the server response. This is achieved by way of the futures returned from didReceiveHead and didReceiveBodyPart. The following functions are part of the “backpressure system” in the delegate:

  • didReceiveHead
  • didReceiveBodyPart
  • didFinishRequest
  • didReceiveError

The first three methods are strictly exclusive, with that exclusivity managed by the futures returned by didReceiveHead and didReceiveBodyPart. What this means is that until the returned future is completed, none of these three methods will be called again. This allows delegates to rate limit the server to a capacity it can manage. didFinishRequest does not return a future, as we are expecting no more data from the server at this time.

didReceiveError is somewhat special: it signals the end of this regime. didRecieveError is not exclusive: it may be called at any time, even if a returned future is not yet completed. didReceiveError is terminal, meaning that once it has been called none of these four methods will be called again. This can be used as a signal to abandon all outstanding work.

Note

This delegate is strongly held by the HTTPTaskHandler for the duration of the Request processing and will be released together with the HTTPTaskHandler when channel is closed. Users of the library are not required to keep a reference to the object that implements this protocol, but may do so if needed.
Show on GitHub

  • Undocumented

    Declaration

    Swift

    associatedtype Response
    Show on GitHub
  • didSendRequestHead(task:_:) Default implementation

    Called when the request head is sent. Will be called once.

    Default Implementation

    Declaration

    Swift

    func didSendRequestHead(task: HTTPClient.Task<Response>, _ head: HTTPRequestHead)

    Parameters

    task

    Current request context.
    head

    Request head.
    Show on GitHub
  • didSendRequestPart(task:_:) Default implementation

    Called when a part of the request body is sent. Could be called zero or more times.

    Default Implementation

    Declaration

    Swift

    func didSendRequestPart(task: HTTPClient.Task<Response>, _ part: IOData)

    Parameters

    task

    Current request context.
    part

    Request body Part.
    Show on GitHub
  • didSendRequest(task:) Default implementation

    Called when the request is fully sent. Will be called once.

    Default Implementation

    Declaration

    Swift

    func didSendRequest(task: HTTPClient.Task<Response>)

    Parameters

    task

    Current request context.
    Show on GitHub
  • didReceiveHead(task:_:) Default implementation

    Called when response head is received. Will be called once. You must return an EventLoopFuture<Void> that you complete when you have finished processing the body part. You can create an already succeeded future by calling task.eventLoop.makeSucceededFuture(()).

    Default Implementation

    Declaration

    Swift

    func didReceiveHead(task: HTTPClient.Task<Response>, _ head: HTTPResponseHead) -> EventLoopFuture<Void>

    Parameters

    task

    Current request context.
    head

    Received reposonse head.

    Return Value

    EventLoopFuture that will be used for backpressure.

    Show on GitHub
  • didReceiveBodyPart(task:_:) Default implementation

    Called when part of a response body is received. Could be called zero or more times. You must return an EventLoopFuture<Void> that you complete when you have finished processing the body part. You can create an already succeeded future by calling task.eventLoop.makeSucceededFuture(()).

    This function will not be called until the future returned by didReceiveHead has completed.

    This function will not be called for subsequent body parts until the previous future returned by a call to this function completes.

    Default Implementation

    Declaration

    Swift

    func didReceiveBodyPart(task: HTTPClient.Task<Response>, _ buffer: ByteBuffer) -> EventLoopFuture<Void>

    Parameters

    task

    Current request context.
    buffer

    Received body Part.

    Return Value

    EventLoopFuture that will be used for backpressure.

    Show on GitHub
  • didReceiveError(task:_:) Default implementation

    Called when error was thrown during request execution. Will be called zero or one time only. Request processing will be stopped after that.

    This function may be called at any time: it does not respect the backpressure exerted by didReceiveHead and didReceiveBodyPart. All outstanding work may be cancelled when this is received. Once called, no further calls will be made to didReceiveHead, didReceiveBodyPart, or didFinishRequest.

    Default Implementation

    Declaration

    Swift

    func didReceiveError(task: HTTPClient.Task<Response>, _ error: Error)

    Parameters

    task

    Current request context.
    error

    Error that occured during response processing.
    Show on GitHub

  • Called when the complete HTTP request is finished. You must return an instance of your Response associated type. Will be called once, except if an error occurred.

    This function will not be called until all futures returned by didReceiveHead and didReceiveBodyPart have completed. Once called, no further calls will be made to didReceiveHead, didReceiveBodyPart, or didReceiveError.

    Declaration

    Swift

    func didFinishRequest(task: HTTPClient.Task<Response>) throws -> Response

    Parameters

    task

    Current request context.

    Return Value

    Result of processing.

    Show on GitHub