libs-base/Headers/Foundation/NSURLSession.h

/**
   NSURLSession.h

   Copyright (C) 2017-2024 Free Software Foundation, Inc.

   Written by: Hugo Melder <hugo@algoriddim.com>
   Date: May 2024

   This file is part of GNUStep-base

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   If you are interested in a warranty or support for this source code,
   contact Scott Christley <scottc@net-community.com> for more information.

   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free
   Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110 USA.
*/

#ifndef __NSURLSession_h_GNUSTEP_BASE_INCLUDE
#define __NSURLSession_h_GNUSTEP_BASE_INCLUDE

#import <Foundation/NSObject.h>
#import <Foundation/NSURLRequest.h>
#import <Foundation/NSHTTPCookieStorage.h>
#import <Foundation/NSArray.h>
#import <Foundation/NSDictionary.h>
#import <Foundation/NSOperation.h>
#import <Foundation/NSProgress.h>
#import <Foundation/NSDate.h>

#if GS_HAVE_NSURLSESSION
#if OS_API_VERSION(MAC_OS_X_VERSION_10_9, GS_API_LATEST)

@protocol NSURLSessionDelegate;
@protocol NSURLSessionTaskDelegate;

@class NSError;
@class NSHTTPURLResponse;
@class NSOperationQueue;
@class NSURL;
@class NSURLAuthenticationChallenge;
@class NSURLCache;
@class NSURLCredential;
@class NSURLCredentialStorage;
@class NSURLRequest;
@class NSURLResponse;
@class NSURLSessionConfiguration;
@class NSURLSessionTask;
@class NSURLSessionDataTask;
@class NSURLSessionUploadTask;
@class NSURLSessionDownloadTask;

NS_ASSUME_NONNULL_BEGIN

typedef void (^GSNSURLSessionDataCompletionHandler)(
  NSData *_Nullable data, NSURLResponse *_Nullable response,
  NSError *_Nullable error);

typedef void (^GSNSURLSessionDownloadCompletionHandler)(
  NSURL *_Nullable location, NSURLResponse *_Nullable response,
  NSError *_Nullable error);

/**
 * NSURLSession is a replacement API for NSURLConnection.  It provides
 * options that affect the policy of, and various aspects of the
 * mechanism by which NSURLRequest objects are retrieved from the
 * network.<br />
 *
 * An NSURLSession may be bound to a delegate object.  The delegate is
 * invoked for certain events during the lifetime of a session.
 *
 * NSURLSession instances are threadsafe.
 *
 * An NSURLSession creates NSURLSessionTask objects which represent the
 * action of a resource being loaded.
 *
 * NSURLSessionTask objects are always created in a suspended state and
 * must be sent the -resume message before they will execute.
 *
 * Subclasses of NSURLSessionTask are used to syntactically
 * differentiate between data and file downloads.
 *
 * An NSURLSessionDataTask receives the resource as a series of calls to
 * the URLSession:dataTask:didReceiveData: delegate method.  This is type of
 * task most commonly associated with retrieving objects for immediate parsing
 * by the consumer.
 */
GS_EXPORT_CLASS
@interface NSURLSession : NSObject
{
@private
  NSOperationQueue          *_delegateQueue;
  id<NSURLSessionDelegate>   _delegate;
  NSURLSessionConfiguration *_configuration;

  NSString *_sessionDescription;
}

+ (NSURLSession *)sharedSession;

+ (NSURLSession *)sessionWithConfiguration:
  (NSURLSessionConfiguration *)configuration;

/*
 * Customization of NSURLSession occurs during creation of a new session.
 * If you do specify a delegate, the delegate will be retained until after
 * the delegate has been sent the URLSession:didBecomeInvalidWithError: message.
 */
+ (NSURLSession *)
  sessionWithConfiguration:(NSURLSessionConfiguration *)configuration
                  delegate:(nullable id<NSURLSessionDelegate>)delegate
             delegateQueue:(nullable NSOperationQueue *)queue;

/* -finishTasksAndInvalidate returns immediately and existing tasks will be
 * allowed to run to completion.  New tasks may not be created.  The session
 * will continue to make delegate callbacks until
 * URLSession:didBecomeInvalidWithError: has been issued.
 *
 * When invalidating a background session, it is not safe to create another
 * background session with the same identifier until
 * URLSession:didBecomeInvalidWithError: has been issued.
 */
- (void)finishTasksAndInvalidate;

/* -invalidateAndCancel acts as -finishTasksAndInvalidate, but issues
 * -cancel to all outstanding tasks for this session.  Note task
 * cancellation is subject to the state of the task, and some tasks may
 * have already have completed at the time they are sent -cancel.
 */
- (void)invalidateAndCancel;

/*
 * NSURLSessionTask objects are always created in a suspended state and
 * must be sent the -resume message before they will execute.
 */

/** Creates a data task with the given request.
 * The request may have a body stream. */
- (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request;

/** Creates a data task to retrieve the contents of the given URL. */
- (NSURLSessionDataTask *)dataTaskWithURL:(NSURL *)url;

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request
                                         fromFile:(NSURL *)fileURL;

- (NSURLSessionUploadTask *)uploadTaskWithRequest:(NSURLRequest *)request
                                         fromData:(NSData *)bodyData;

- (NSURLSessionUploadTask *)uploadTaskWithStreamedRequest:
  (NSURLRequest *)request;

/* Creates a download task with the given request. */
- (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request;

/* Creates a download task to download the contents of the given URL. */
- (NSURLSessionDownloadTask *)downloadTaskWithURL:(NSURL *)url;

- (NSURLSessionDownloadTask *)downloadTaskWithResumeData:(NSData *)resumeData;

- (void)getTasksWithCompletionHandler:
  (void (^)(NSArray<NSURLSessionDataTask *>     *dataTasks,
            NSArray<NSURLSessionUploadTask *>   *uploadTasks,
            NSArray<NSURLSessionDownloadTask *> *downloadTasks))
    completionHandler;

- (void)getAllTasksWithCompletionHandler:
  (void (^)(GS_GENERIC_CLASS(NSArray, __kindof NSURLSessionTask *) * tasks))
    completionHandler;

/**
 * This serial NSOperationQueue queue is used for dispatching delegate messages
 * and completion handlers.
 */
- (NSOperationQueue *)delegateQueue;

/**
 * The delegate for the session. This is the object to which delegate messages
 * will be sent.
 *
 * The session keeps a strong reference to the delegate.
 */
- (nullable id<NSURLSessionDelegate>)delegate;

/**
 * The configuration object used to create the session.
 *
 * A copy of the configuration object is made.
 * Changes to the configuration object after the session is created have no
 * effect.
 */
- (NSURLSessionConfiguration *)configuration;

/**
 * An App-specific description of the session.
 */
- (nullable NSString *)sessionDescription;

/**
 * Sets an app-specific description of the session.
 */
- (void)setSessionDescription:(NSString *)description;

@end

/*
 * NSURLSession convenience routines deliver results to
 * a completion handler block.  These convenience routines
 * are not available to NSURLSessions that are configured
 * as background sessions.
 *
 * Task objects are always created in a suspended state and
 * must be sent the -resume message before they will execute.
 */
@interface
NSURLSession (NSURLSessionAsynchronousConvenience)
/*
 * data task convenience methods.  These methods create tasks that
 * bypass the normal delegate calls for response and data delivery,
 * and provide a simple cancelable asynchronous interface to receiving
 * data.  Errors will be returned in the NSURLErrorDomain,
 * see <Foundation/NSURLError.h>.  The delegate, if any, will still be
 * called for authentication challenges.
 */
- (NSURLSessionDataTask *)
  dataTaskWithRequest:(NSURLRequest *)request
    completionHandler:(GSNSURLSessionDataCompletionHandler)completionHandler;
- (NSURLSessionDataTask *)dataTaskWithURL:(NSURL *)url
                        completionHandler:(GSNSURLSessionDataCompletionHandler)
                                            completionHandler;

- (NSURLSessionUploadTask *)
  uploadTaskWithRequest:(NSURLRequest *)request
               fromFile:(NSURL *)fileURL
      completionHandler:(GSNSURLSessionDataCompletionHandler)completionHandler;

- (NSURLSessionUploadTask *)
  uploadTaskWithRequest:(NSURLRequest *)request
               fromData:(NSData *)bodyData
      completionHandler:(GSNSURLSessionDataCompletionHandler)completionHandler;

/*
 * download task convenience methods.  When a download successfully
 * completes, the NSURL will point to a file that must be read or
 * copied during the invocation of the completion routine.  The file
 * will be removed automatically.
 */
- (NSURLSessionDownloadTask *)downloadTaskWithRequest:(NSURLRequest *)request
                                    completionHandler:
                                      (GSNSURLSessionDownloadCompletionHandler)
                                        completionHandler;
- (NSURLSessionDownloadTask *)downloadTaskWithURL:(NSURL *)url
                                completionHandler:
                                  (GSNSURLSessionDownloadCompletionHandler)
                                    completionHandler;

- (NSURLSessionDownloadTask *)
  downloadTaskWithResumeData:(NSData *)resumeData
           completionHandler:
             (GSNSURLSessionDownloadCompletionHandler)completionHandler;

@end

typedef NS_ENUM(NSUInteger, NSURLSessionTaskState) {
  /* The task is currently being serviced by the session */
  NSURLSessionTaskStateRunning = 0,
  NSURLSessionTaskStateSuspended = 1,
  /* The task has been told to cancel.
   * The session will receive URLSession:task:didCompleteWithError:. */
  NSURLSessionTaskStateCanceling = 2,
  /* The task has completed and the session will receive no more
   * delegate notifications */
  NSURLSessionTaskStateCompleted = 3,
};

GS_EXPORT const float NSURLSessionTaskPriorityDefault;
GS_EXPORT const float NSURLSessionTaskPriorityLow;
GS_EXPORT const float NSURLSessionTaskPriorityHigh;

GS_EXPORT const int64_t NSURLSessionTransferSizeUnknown;

/*
 * NSURLSessionTask - a cancelable object that refers to the lifetime
 * of processing a given request.
 */
GS_EXPORT_CLASS
@interface NSURLSessionTask : NSObject <NSCopying, NSProgressReporting>
{
  NSUInteger    _taskIdentifier;
  NSURLRequest *_originalRequest;

  id<NSURLSessionTaskDelegate> _delegate;
  NSURLSessionTaskState        _state;
  NSURLRequest                *_currentRequest;
  NSURLResponse               *_response;
  NSProgress                  *_progress;
  NSDate                      *_earliestBeginDate;

  _Atomic(int64_t) _countOfBytesClientExpectsToSend;
  _Atomic(int64_t) _countOfBytesClientExpectsToReceive;
  _Atomic(int64_t) _countOfBytesSent;
  _Atomic(int64_t) _countOfBytesReceived;
  _Atomic(int64_t) _countOfBytesExpectedToSend;
  _Atomic(int64_t) _countOfBytesExpectedToReceive;
  _Atomic(double)  _priority;

  NSString *_taskDescription;
  NSError  *_error;
}

- (NSUInteger)taskIdentifier;

- (nullable NSURLRequest *)originalRequest;
- (nullable NSURLRequest *)currentRequest;
- (nullable NSURLResponse *)response;

- (NSURLSessionTaskState)state;
- (NSProgress *)progress;
- (nullable NSError *)error;

- (nullable id<NSURLSessionTaskDelegate>)delegate;
- (void)setDelegate:(nullable id<NSURLSessionTaskDelegate>)delegate;

- (nullable NSDate *)earliestBeginDate;
- (void)setEarliestBeginDate:(nullable NSDate *)date;

- (int64_t)countOfBytesClientExpectsToSend;
- (int64_t)countOfBytesClientExpectsToReceive;
- (int64_t)countOfBytesSent;
- (int64_t)countOfBytesReceived;
- (int64_t)countOfBytesExpectedToSend;
- (int64_t)countOfBytesExpectedToReceive;

/**
 * App-specific description of the task.
 */
- (nullable NSString *)taskDescription;

/**
 * Sets an app-specific description of the task.
 */
- (void)setTaskDescription:(nullable NSString *)description;

/**
 * Cancels the task and the ongoing transfer.
 */
- (void)cancel;

- (void)suspend;
- (void)resume;

- (float)priority;
- (void)setPriority:(float)priority;

@end

GS_EXPORT_CLASS
@interface NSURLSessionDataTask : NSURLSessionTask
{
  void *_completionHandler;
}
@end

GS_EXPORT_CLASS
@interface NSURLSessionUploadTask : NSURLSessionDataTask
@end

GS_EXPORT_CLASS
@interface NSURLSessionDownloadTask : NSURLSessionTask
{
  void   *_completionHandler;
  int64_t _countOfBytesWritten;
}
@end

#if OS_API_VERSION(MAC_OS_X_VERSION_10_11, GS_API_LATEST)
GS_EXPORT_CLASS
@interface NSURLSessionStreamTask : NSURLSessionTask
@end
#endif

/*
 * Configuration options for an NSURLSession.  When a session is
 * created, a copy of the configuration object is made - you cannot
 * modify the configuration of a session after it has been created.
 */
GS_EXPORT_CLASS
@interface NSURLSessionConfiguration : NSObject <NSCopying>
{
  NSString                *_identifier;
  NSURLCache              *_URLCache;
  NSURLRequestCachePolicy  _requestCachePolicy;
  NSArray                 *_protocolClasses;
  NSInteger                _HTTPMaximumConnectionLifetime;
  NSInteger                _HTTPMaximumConnectionsPerHost;
  BOOL                     _HTTPShouldUsePipelining;
  NSHTTPCookieAcceptPolicy _HTTPCookieAcceptPolicy;
  NSHTTPCookieStorage     *_HTTPCookieStorage;
  NSURLCredentialStorage  *_URLCredentialStorage;
  BOOL                     _HTTPShouldSetCookies;
  NSDictionary            *_HTTPAdditionalHeaders;
  NSTimeInterval           _timeoutIntervalForRequest;
  NSTimeInterval           _timeoutIntervalForResource;
}

- (NSURLRequest *)configureRequest:(NSURLRequest *)request;

+ (NSURLSessionConfiguration *)defaultSessionConfiguration;
+ (NSURLSessionConfiguration *)ephemeralSessionConfiguration;
+ (NSURLSessionConfiguration *)backgroundSessionConfigurationWithIdentifier:
  (NSString *)identifier;

- (nullable NSDictionary *)HTTPAdditionalHeaders;
- (void)setHTTPAdditionalHeaders:(NSDictionary *)headers;

/**
 * Gets the timeout interval to use when waiting for additional data to arrive.
 * The request timeout interval controls how long (in seconds) a task should
 * wait for additional data to arrive before giving up. The timer is reset
 * whenever new data arrives. When the request timer reaches the specified
 * interval without receiving any new data, it triggers a timeout.
 *
 * Currently not used by NSURLSession.
 */
- (NSTimeInterval)timeoutIntervalForRequest;
/**
 * Sets the timeout interval to use when waiting for additional data to arrive.
 */
- (void)setTimeoutIntervalForRequest:(NSTimeInterval)interval;

/**
 * Gets the maximum amount of time that a resource request should be allowed to
 * take. The resource timeout interval controls how long (in seconds) to wait
 * for an entire resource to transfer before giving up. The resource timer
 * starts when the request is initiated and counts until either the request
 * completes or this timeout interval is reached, whichever comes first.
 */
- (NSTimeInterval)timeoutIntervalForResource;
/**
 * Sets the maximum amount of time that a resource request should be allowed to
 * take.
 */
- (void)setTimeoutIntervalForResource:(NSTimeInterval)interval;

- (NSHTTPCookieAcceptPolicy)HTTPCookieAcceptPolicy;
- (void)setHTTPCookieAcceptPolicy:(NSHTTPCookieAcceptPolicy)policy;

- (nullable NSHTTPCookieStorage *)HTTPCookieStorage;
- (void)setHTTPCookieStorage:(NSHTTPCookieStorage *)storage;

- (NSInteger)HTTPMaximumConnectionsPerHost;
- (void)setHTTPMaximumConnectionsPerHost:(NSInteger)n;

/**
 * Indicates whether the session should set cookies.
 *
 * This property controls whether tasks within sessions based on this
 * configuration should automatically include cookies from the shared cookie
 * store when making requests.
 *
 * If set to NO, you must manually provide cookies by adding a Cookie header
 * through the session's HTTPAdditionalHeaders property or on a per-request
 * basis using a custom NSURLRequest object.
 *
 * The default value is YES.
 *
 * See Also:
 * - HTTPCookieAcceptPolicy
 * - HTTPCookieStorage
 * - NSHTTPCookieStorage
 * - NSHTTPCookie
 */
- (BOOL)HTTPShouldSetCookies;

/**
 * Sets whether the session should set cookies.
 *
 * This method controls whether tasks within sessions based on this
 * configuration should automatically include cookies from the shared cookie
 * store when making requests.
 *
 * If set to NO, you must manually provide cookies by adding a Cookie header
 * through the session's HTTPAdditionalHeaders property or on a per-request
 * basis using a custom NSURLRequest object.
 *
 * The default value is YES.
 *
 * See Also:
 * - HTTPCookieAcceptPolicy
 * - HTTPCookieStorage
 * - NSHTTPCookieStorage
 * - NSHTTPCookie
 */
- (void)setHTTPShouldSetCookies:(BOOL)flag;

/**
 * HTTP/1.1 pipelining is not implemented. This flag is ignored.
 */
- (BOOL)HTTPShouldUsePipelining;
- (void)setHTTPShouldUsePipelining:(BOOL)flag;

- (nullable NSString *)identifier;

- (nullable NSArray *)protocolClasses;

- (NSURLRequestCachePolicy)requestCachePolicy;
- (void)setRequestCachePolicy:(NSURLRequestCachePolicy)policy;

- (nullable NSURLCache *)URLCache;
- (void)setURLCache:(NSURLCache *)cache;

- (nullable NSURLCredentialStorage *)URLCredentialStorage;
- (void)setURLCredentialStorage:(NSURLCredentialStorage *)storage;

#if !NO_GNUSTEP
/** Permits a session to be configured so that older connections are reused.
 * A value of zero or less uses the default behavior where connections are
 * reused as long as they are not older than 118 seconds, which is reasonable
 * for the vast majority if situations.
 */
- (NSInteger)HTTPMaximumConnectionLifetime;
- (void)setHTTPMaximumConnectionLifetime:(NSInteger)n;
#endif

@end

typedef NS_ENUM(NSInteger, NSURLSessionAuthChallengeDisposition) {
  NSURLSessionAuthChallengeUseCredential = 0,
  NSURLSessionAuthChallengePerformDefaultHandling = 1,
  NSURLSessionAuthChallengeCancelAuthenticationChallenge = 2,
  NSURLSessionAuthChallengeRejectProtectionSpace = 3
};

typedef NS_ENUM(NSInteger, NSURLSessionResponseDisposition) {
  NSURLSessionResponseCancel = 0,
  NSURLSessionResponseAllow = 1,
  NSURLSessionResponseBecomeDownload = 2,
  NSURLSessionResponseBecomeStream = 3
};

@protocol NSURLSessionDelegate <NSObject>
@optional
/* The last message a session receives.  A session will only become
 * invalid because of a systemic error or when it has been
 * explicitly invalidated, in which case the error parameter will be nil.
 */
- (void)URLSession:(NSURLSession *)session
  didBecomeInvalidWithError:(nullable NSError *)error;

/* Implementing this method permits a delegate to provide authentication
 * credentials in response to a challenge from the remote server.
 */
- (void)URLSession:(NSURLSession *)session
  didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge
    completionHandler:
      (void (^)(NSURLSessionAuthChallengeDisposition disposition,
                NSURLCredential                     *credential))handler;

@end

@protocol NSURLSessionTaskDelegate <NSURLSessionDelegate>
@optional

#if OS_API_VERSION(MAC_OS_VERSION_13_0, GS_API_LATEST)
- (void)URLSession:(NSURLSession *)session
     didCreateTask:(NSURLSessionTask *)task;
#endif

/* Sent as the last message related to a specific task.  Error may be
 * nil, which implies that no error occurred and this task is complete.
 */
- (void)URLSession:(NSURLSession *)session
                  task:(NSURLSessionTask *)task
  didCompleteWithError:(nullable NSError *)error;

/* Called to request authentication credentials from the delegate when
 * an authentication request is received from the server which is specific
 * to this task.
 */
- (void)URLSession:(NSURLSession *)session
                 task:(NSURLSessionTask *)task
  didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge
    completionHandler:
      (void (^)(NSURLSessionAuthChallengeDisposition disposition,
                NSURLCredential                     *credential))handler;

/* Periodically informs the delegate of the progress of sending body content
 * to the server.
 */
- (void)URLSession:(NSURLSession *)session
                      task:(NSURLSessionTask *)task
           didSendBodyData:(int64_t)bytesSent
            totalBytesSent:(int64_t)totalBytesSent
  totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend;

/* An HTTP request is attempting to perform a redirection to a different
 * URL. You must invoke the completion routine to allow the
 * redirection, allow the redirection with a modified request, or
 * pass nil to the completionHandler to cause the body of the redirection
 * response to be delivered as the payload of this request. The default
 * is to follow redirections.
 *
 */
- (void)URLSession:(NSURLSession *)session
                        task:(NSURLSessionTask *)task
  willPerformHTTPRedirection:(NSHTTPURLResponse *)response
                  newRequest:(NSURLRequest *)request
           completionHandler:(void (^)(NSURLRequest *))completionHandler;

- (void)URLSession:(NSURLSession *)session
               task:(NSURLSessionTask *)task
  needNewBodyStream:(void (^)(NSInputStream *bodyStream))completionHandler;

@end

@protocol NSURLSessionDataDelegate <NSURLSessionTaskDelegate>
@optional
/* Sent when data is available for the delegate to consume.
 */
- (void)URLSession:(NSURLSession *)session
          dataTask:(NSURLSessionDataTask *)dataTask
    didReceiveData:(NSData *)data;

/** Informs the delegate of a response.  This message is sent when all the
 * response headers have arrived, before the body of the response arrives.
 */
- (void)URLSession:(NSURLSession *)session
            dataTask:(NSURLSessionDataTask *)dataTask
  didReceiveResponse:(NSURLResponse *)response
   completionHandler:
     (void (^)(NSURLSessionResponseDisposition disposition))completionHandler;

@end

@protocol NSURLSessionDownloadDelegate <NSURLSessionTaskDelegate>

/* Sent when a download task that has completed a download.  The delegate should
 * copy or move the file at the given location to a new location as it will be
 * removed when the delegate message returns.
 * URLSession:task:didCompleteWithError: will still be called.
 */
- (void)URLSession:(NSURLSession *)session
               downloadTask:(NSURLSessionDownloadTask *)downloadTask
  didFinishDownloadingToURL:(NSURL *)location;

@optional
/* Sent periodically to notify the delegate of download progress. */
- (void)URLSession:(NSURLSession *)session
               downloadTask:(NSURLSessionDownloadTask *)downloadTask
               didWriteData:(int64_t)bytesWritten
          totalBytesWritten:(int64_t)totalBytesWritten
  totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite;

/* Sent when a download has been resumed. If a download failed with an
 * error, the -userInfo dictionary of the error will contain an
 * NSURLSessionDownloadTaskResumeData key, whose value is the resume
 * data.
 */
- (void)URLSession:(NSURLSession *)session
        downloadTask:(NSURLSessionDownloadTask *)downloadTask
   didResumeAtOffset:(int64_t)fileOffset
  expectedTotalBytes:(int64_t)expectedTotalBytes;

@end

NS_ASSUME_NONNULL_END

#endif /* MAC_OS_X_VERSION_10_9 */
#endif /* GS_HAVE_NSURLSESSION */
#endif /* __NSURLSession_h_GNUSTEP_BASE_INCLUDE */