Sources/SPTDataLoader/SPTDataLoaderRequestResponseHandler.h

/*
 Copyright Spotify AB.
 SPDX-License-Identifier: Apache-2.0
 */

#import <Foundation/Foundation.h>

@class SPTDataLoaderRequest;
@class SPTDataLoaderResponse;

@protocol SPTDataLoaderRequestResponseHandler;

NS_ASSUME_NONNULL_BEGIN

/**
 A private delegate API for the creator of SPTDataLoader to use for routing requests through a user authentication
 layer
 */
@protocol SPTDataLoaderRequestResponseHandlerDelegate <NSObject>

/**
 Performs a request
 @param requestResponseHandler The object that can perform requests and responses
 @param request The object describing the request to perform
 */
- (void)requestResponseHandler:(id<SPTDataLoaderRequestResponseHandler>)requestResponseHandler
                performRequest:(SPTDataLoaderRequest *)request;
/**
 Cancels a request
 @param requestResponseHandler The object that can perform cancels
 @param request The object describing the request to cancel
 */
- (void)requestResponseHandler:(id<SPTDataLoaderRequestResponseHandler>)requestResponseHandler
                 cancelRequest:(SPTDataLoaderRequest *)request;

@optional

/**
 Delegate a successfully authorised request
 @param requestResponseHandler The handler that successfully authorised the request
 @param request The request that contains the authorisation headers
 */
- (void)requestResponseHandler:(id<SPTDataLoaderRequestResponseHandler>)requestResponseHandler
             authorisedRequest:(SPTDataLoaderRequest *)request;
/**
 Delegate a failed authorisation attempt for a request
 @param requestResponseHandler The handler that failed to authorise the request
 @param request The request whose authorisation failed
 @param error The object describing the failure in the authorisation request
 */
- (void)requestResponseHandler:(id<SPTDataLoaderRequestResponseHandler>)requestResponseHandler
      failedToAuthoriseRequest:(SPTDataLoaderRequest *)request
                         error:(NSError *)error;

@end

@protocol SPTDataLoaderRequestResponseHandler <NSObject>

/**
 The object to delegate performing requests to
 */
@property (nonatomic, weak, readonly, nullable) id<SPTDataLoaderRequestResponseHandlerDelegate> requestResponseHandlerDelegate;

/**
 Call when a response successfully completed
 @param response The response that successfully completed
 */
- (void)successfulResponse:(SPTDataLoaderResponse *)response;
/**
 Call when a response failed to complete
 @param response The response that failed to complete
 */
- (void)failedResponse:(SPTDataLoaderResponse *)response;
/**
 Call when a request becomes cancelled
 @param request The request that was cancelled
 */
- (void)cancelledRequest:(SPTDataLoaderRequest *)request;
/**
 Called when a chunk is received
 @param data The data received by the request
 @param response The response the chunk is received for
 */
- (void)receivedDataChunk:(NSData *)data forResponse:(SPTDataLoaderResponse *)response;
/**
 Called when the headers for a response are received
 @param response The response containing the initial information (such as headers)
 */
- (void)receivedInitialResponse:(SPTDataLoaderResponse *)response;
/**
 Called when a request with waitsForConnectivity enters the waiting state
 @param request The request that is waiting
 */
- (void)requestIsWaitingForConnectivity:(SPTDataLoaderRequest *)request;

/**
 Called when a request using the @c bodyStream property encounters some sort of redirection that invalidates
 the initially provided input stream.
 @param completionHandler The completion handler that is to be called with the new input stream.
 @param request The request that needs a new input stream.
 */
- (void)needsNewBodyStream:(void (^)(NSInputStream *))completionHandler
                forRequest:(SPTDataLoaderRequest *)request;

@optional

/**
 Whether the request needs authorisation according to this handler
 @param request The request that may need authorisation
 */
- (BOOL)shouldAuthoriseRequest:(SPTDataLoaderRequest *)request;
/**
 Authorise a request
 @param request The request to be authorise
 */
- (void)authoriseRequest:(SPTDataLoaderRequest *)request;

@end

NS_ASSUME_NONNULL_END