RequestDelegate

public protocol RequestDelegate

Allows you to create Requests with custom logic. This is useful for taking things that are not standard network requests, and wrapping them so they look to Siesta as if they are. To create a custom request, pass your delegate to Resource.prepareRequest(using:).

You can also implement Siesta’s Request protocol yourself, but this is a daunting task full of pitfalls and redundant effort. This protocol provides customization points for only the things custom requests typically need to customize, and provides standard behavior and sanity checks. In particular, using RequestDelegate:

  • provides standard implementations for all the request hooks,
  • ensures those hooks are called exactly once, even if your delegate misbehaves and reports multiple responses,
  • tracks request state and ensures valid state transitions,
  • polls request progress, and
  • handles cancellation cleanly, preventing “response after cancel” race conditions.

Siesta itself uses this protocol to implement its own requests. Look at NetworkRequestDelegate and RequestChainDelgate in Siesta’s source code for examples of implementing this protocol.

See also

Resource.prepareRequest(using:)

  • The delegate should commence the operation (e.g. network call) that will eventually produce a response.

    Siesta will call this method at most once per call to Resource.prepareRequest(using:).

    Implementations of this method MUST eventually call completionHandler.broadcastResponse(...). They will typically want to hold on to the completionHandler for the duration of a long-running operation in order to broadcast the response at the end.

    Declaration

    Swift

    func startUnderlyingOperation(passingResponseTo completionHandler: RequestCompletionHandler)
    Show on GitHub

  • Indicates that the Request using this delegate has been cancelled, and the delegate MAY cancel its underlying operation as well.

    Declaration

    Swift

    func cancelUnderlyingOperation()
    Show on GitHub

  • Returns another delegate which would perform the same underlying operation as this one. What consitutes the “same operation” is delegate-specific; for example, the new delegate may re-read relevant resource configuration.

    If you never use Request.repeated(), you can decline to implement this by calling fatalError().

    Declaration

    Swift

    func repeated() -> RequestDelegate
    Show on GitHub
  • computeProgress() Default implementation

    Asks your delegate to report progress ranging from 0 to 1. Implementations may be as accurate or as inaccurate as they wish. Values returned by this method SHOULD increase monotonically.

    Siesta will ensure that a Request reports progress of 1 when completed, regardless of what this method returns.

    Default Implementation

    Returns a constant 0.

    Declaration

    Swift

    func computeProgress() -> Double
    Show on GitHub
  • progressReportingInterval Default implementation

    The time interval at which you would like your computeProgress() method to be called.

    Default Implementation

    1/20th of a second.

    Declaration

    Swift

    var progressReportingInterval: TimeInterval { get }
    Show on GitHub

  • A description of the underlying operation suitable for logging and debugging.

    Declaration

    Swift

    var requestDescription: String { get }
    Show on GitHub