mirror of
https://github.com/swisspol/GCDWebServer.git
synced 2026-04-24 00:00:04 +08:00
#33 Documented Core/
This commit is contained in:
Pierre-Olivier Latour
@@ -30,8 +30,14 @@
|
||||
#import "GCDWebServerRequest.h"
|
||||
#import "GCDWebServerResponse.h"
|
||||
|
||||
/**
|
||||
* Log levels used by GCDWebServer.
|
||||
*
|
||||
* @warning kGCDWebServerLogLevel_Debug is only available if "NDEBUG" is not
|
||||
* defined when building.
|
||||
*/
|
||||
typedef NS_ENUM(int, GCDWebServerLogLevel) {
|
||||
kGCDWebServerLogLevel_Debug = 0, // Only available if "NDEBUG" is not defined when building
|
||||
kGCDWebServerLogLevel_Debug = 0,
|
||||
kGCDWebServerLogLevel_Verbose,
|
||||
kGCDWebServerLogLevel_Info,
|
||||
kGCDWebServerLogLevel_Warning,
|
||||
@@ -39,88 +45,420 @@ typedef NS_ENUM(int, GCDWebServerLogLevel) {
|
||||
kGCDWebServerLogLevel_Exception,
|
||||
};
|
||||
|
||||
/**
|
||||
* The GCDWebServerMatchBlock is called for every handler added to the
|
||||
* GCDWebServer whenever a new HTTP request has started (i.e. HTTP headers have
|
||||
* been received). The block is passed the basic info for the request (HTTP method,
|
||||
* URL, headers...) and must decide if it wants to handle it or not.
|
||||
*
|
||||
* If the handler can handle the request, the block must return a new
|
||||
* GCDWebServerRequest instance created with the same basic info.
|
||||
* Otherwise, it simply returns nil.
|
||||
*/
|
||||
typedef GCDWebServerRequest* (^GCDWebServerMatchBlock)(NSString* requestMethod, NSURL* requestURL, NSDictionary* requestHeaders, NSString* urlPath, NSDictionary* urlQuery);
|
||||
|
||||
/**
|
||||
* The GCDWebServerProcessBlock is called after the HTTP request has been fully
|
||||
* received (i.e. the entire HTTP body has been read). THe block is passed the
|
||||
* GCDWebServerRequest created at the previous step by the GCDWebServerMatchBlock.
|
||||
*
|
||||
* The block must return a GCDWebServerResponse or nil on error, which will
|
||||
* result in a 500 HTTP status code returned to the client. It's however
|
||||
* recommended to return a GCDWebServerErrorResponse on error so more useful
|
||||
* information can be returned to the client.
|
||||
*/
|
||||
typedef GCDWebServerResponse* (^GCDWebServerProcessBlock)(GCDWebServerRequest* request);
|
||||
|
||||
extern NSString* const GCDWebServerOption_Port; // NSNumber / NSUInteger (default is 0 i.e. use a random port)
|
||||
extern NSString* const GCDWebServerOption_BonjourName; // NSString (default is empty string i.e. use computer name)
|
||||
extern NSString* const GCDWebServerOption_MaxPendingConnections; // NSNumber / NSUInteger (default is 16)
|
||||
extern NSString* const GCDWebServerOption_ServerName; // NSString (default is server class name)
|
||||
extern NSString* const GCDWebServerOption_AuthenticationMethod; // One of "GCDWebServerAuthenticationMethod_..." (default is nil i.e. no authentication)
|
||||
extern NSString* const GCDWebServerOption_AuthenticationRealm; // NSString (default is server name)
|
||||
extern NSString* const GCDWebServerOption_AuthenticationAccounts; // NSDictionary of username / password (default is nil i.e. no accounts)
|
||||
extern NSString* const GCDWebServerOption_ConnectionClass; // Subclass of GCDWebServerConnection (default is GCDWebServerConnection class)
|
||||
extern NSString* const GCDWebServerOption_AutomaticallyMapHEADToGET; // NSNumber / BOOL (default is YES)
|
||||
extern NSString* const GCDWebServerOption_ConnectedStateCoalescingInterval; // NSNumber / double (default is 1.0 seconds - set to <=0.0 to disable coaslescing of -webServerDidConnect: / -webServerDidDisconnect:)
|
||||
/**
|
||||
* The port used by the GCDWebServer (NSNumber / NSUInteger).
|
||||
*
|
||||
* Default value is 0 i.e. let the OS pick a random port.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_Port;
|
||||
|
||||
/**
|
||||
* The Bonjour name used by the GCDWebServer (NSString).
|
||||
*
|
||||
* Default value is an empty string i.e. use the computer / device name.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_BonjourName;
|
||||
|
||||
/**
|
||||
* The maximum number of incoming HTTP requests that can be queued waiting to
|
||||
* be handled before new ones are dropped (NSNumber / NSUInteger).
|
||||
*
|
||||
* Default value is 16.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_MaxPendingConnections;
|
||||
|
||||
/**
|
||||
* The value for "Server" HTTP header used by the GCDWebServer (NSString).
|
||||
*
|
||||
* Default value is the GCDWebServer class name.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_ServerName;
|
||||
|
||||
/**
|
||||
* The authentication method used by the GCDWebServer
|
||||
* (one of "GCDWebServerAuthenticationMethod_...").
|
||||
*
|
||||
* Default value is nil i.e. authentication disabled.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_AuthenticationMethod;
|
||||
|
||||
/**
|
||||
* The authentication realm used by the GCDWebServer (NSString).
|
||||
*
|
||||
* Default value is the same as GCDWebServerOption_ServerName.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_AuthenticationRealm;
|
||||
|
||||
/**
|
||||
* The authentication accounts used by the GCDWebServer
|
||||
* (NSDictionary of username / password pairs).
|
||||
*
|
||||
* Default value is nil i.e. no accounts.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_AuthenticationAccounts;
|
||||
|
||||
/**
|
||||
* The class used by the GCDWebServer when instantiating GCDWebServerConnection
|
||||
* (subclass of GCDWebServerConnection).
|
||||
*
|
||||
* Default value is GCDWebServerConnection class.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_ConnectionClass;
|
||||
|
||||
/**
|
||||
* Allow the GCDWebServer to pretend "HEAD" requests are actually "GET" ones
|
||||
* and automatically discard the HTTP body of the response (NSNumber / BOOL).
|
||||
*
|
||||
* Default value is YES.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_AutomaticallyMapHEADToGET;
|
||||
|
||||
/**
|
||||
* The interval expressed in seconds used by the GCDWebServer to decide how to
|
||||
* coalesce calls to -webServerDidConnect: and -webServerDidDisconnect:
|
||||
* (NSNumber / double). Coalescing will be disabled if the interval is <= 0.0.
|
||||
*
|
||||
* Default value is 1.0 second.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_ConnectedStateCoalescingInterval;
|
||||
|
||||
#if TARGET_OS_IPHONE
|
||||
extern NSString* const GCDWebServerOption_AutomaticallySuspendInBackground; // NSNumber / BOOL (default is YES)
|
||||
|
||||
/**
|
||||
* Enables the GCDWebServer to automatically suspend itself (as if -stop was
|
||||
* called) when the iOS app goes into the background and the last
|
||||
* GCDWebServerConnection is closed, then resume itself (as if -start was called)
|
||||
* when the iOS app comes back to the foreground (NSNumber / BOOL).
|
||||
*
|
||||
* See the README.md file for more information about this option.
|
||||
*
|
||||
* Default value is YES.
|
||||
*
|
||||
* @warning The running property will be NO while the GCDWebServer is suspended.
|
||||
*/
|
||||
extern NSString* const GCDWebServerOption_AutomaticallySuspendInBackground;
|
||||
|
||||
#endif
|
||||
|
||||
extern NSString* const GCDWebServerAuthenticationMethod_Basic; // Not recommended as password is sent in clear
|
||||
/**
|
||||
* HTTP Basic Authentication scheme (see https://tools.ietf.org/html/rfc2617).
|
||||
*
|
||||
* @warning Use of this method is not recommended as the passwords are sent in clear.
|
||||
*/
|
||||
extern NSString* const GCDWebServerAuthenticationMethod_Basic;
|
||||
|
||||
/**
|
||||
* HTTP Digest Access Authentication scheme (see https://tools.ietf.org/html/rfc2617).
|
||||
*/
|
||||
extern NSString* const GCDWebServerAuthenticationMethod_DigestAccess;
|
||||
|
||||
@class GCDWebServer;
|
||||
|
||||
// These methods are always called on main thread
|
||||
/**
|
||||
* Delegate methods for GCDWebServer.
|
||||
*
|
||||
* @warning These methods are always called on the main thread in a serialized way.
|
||||
*/
|
||||
@protocol GCDWebServerDelegate <NSObject>
|
||||
@optional
|
||||
|
||||
/**
|
||||
* This method is called after the server has succesfully started.
|
||||
*/
|
||||
- (void)webServerDidStart:(GCDWebServer*)server;
|
||||
- (void)webServerDidConnect:(GCDWebServer*)server; // Called when first connection is opened
|
||||
- (void)webServerDidDisconnect:(GCDWebServer*)server; // Called when last connection is closed
|
||||
|
||||
/**
|
||||
* This method is called when the first GCDWebServerConnection is opened by the
|
||||
* server to serve a series of HTTP requests. A series is ongoing as long as
|
||||
* new HTTP requests keep coming (and new GCDWebServerConnection instances keep
|
||||
* being opened), before the last HTTP request has been responded to (and the
|
||||
* corresponding last GCDWebServerConnection closed).
|
||||
*/
|
||||
- (void)webServerDidConnect:(GCDWebServer*)server;
|
||||
|
||||
/**
|
||||
* This method is called when the last GCDWebServerConnection is closed after
|
||||
* the server has served a series of HTTP requests.
|
||||
*
|
||||
* The GCDWebServerOption_ConnectedStateCoalescingInterval option can be used
|
||||
* to have the server wait some extra delay before considering that the series
|
||||
* of HTTP requests has ended (in case there some latency between consecutive
|
||||
* requests). This effectively coalesces the calls to -webServerDidConnect:
|
||||
* and -webServerDidDisconnect:.
|
||||
*/
|
||||
- (void)webServerDidDisconnect:(GCDWebServer*)server;
|
||||
|
||||
/**
|
||||
* This method is called after the server has stopped.
|
||||
*/
|
||||
- (void)webServerDidStop:(GCDWebServer*)server;
|
||||
|
||||
@end
|
||||
|
||||
/**
|
||||
* The GCDWebServer class manages the socket that listens for HTTP requests and
|
||||
* the list of handlers used to respond to them.
|
||||
*
|
||||
* See the README.md file for more information about the architecture of GCDWebServer.
|
||||
*/
|
||||
@interface GCDWebServer : NSObject
|
||||
|
||||
/**
|
||||
* Sets the delegate for the server.
|
||||
*/
|
||||
@property(nonatomic, assign) id<GCDWebServerDelegate> delegate;
|
||||
|
||||
/**
|
||||
* Indicates if the server is currently running.
|
||||
*/
|
||||
@property(nonatomic, readonly, getter=isRunning) BOOL running;
|
||||
@property(nonatomic, readonly) NSUInteger port; // Only non-zero if running
|
||||
@property(nonatomic, readonly) NSString* bonjourName; // Only non-nil if Bonjour registration is active
|
||||
|
||||
/**
|
||||
* Returns the port used by the server.
|
||||
*
|
||||
* @warning This property is only valid if the server is running.
|
||||
*/
|
||||
@property(nonatomic, readonly) NSUInteger port;
|
||||
|
||||
/**
|
||||
* Returns the Bonjour name in used by the server.
|
||||
*
|
||||
* @warning This property is only valid if the server is running and Bonjour
|
||||
* registration has successfully completed, which can take up to a few seconds.
|
||||
*/
|
||||
@property(nonatomic, readonly) NSString* bonjourName;
|
||||
|
||||
/**
|
||||
* This method is the designated initializer for the class.
|
||||
*/
|
||||
- (instancetype)init;
|
||||
|
||||
/**
|
||||
* Adds a handler to the server to handle incoming HTTP requests.
|
||||
* Handlers are called in a LIFO queue, so the latest added handler overrides
|
||||
* any previously added ones.
|
||||
*
|
||||
* @warning Addling handlers while the GCDWebServer is running is not allowed.
|
||||
*/
|
||||
- (void)addHandlerWithMatchBlock:(GCDWebServerMatchBlock)matchBlock processBlock:(GCDWebServerProcessBlock)processBlock;
|
||||
|
||||
/**
|
||||
* Removes all handlers previously added to the server.
|
||||
*
|
||||
* @warning Removing handlers while the GCDWebServer is running is not allowed.
|
||||
*/
|
||||
- (void)removeAllHandlers;
|
||||
|
||||
- (BOOL)start; // Default is port 8080 (OS X & iOS Simulator) or 80 (iOS) and computer / device name for Bonjour
|
||||
- (BOOL)startWithPort:(NSUInteger)port bonjourName:(NSString*)name; // Pass nil name to disable Bonjour or empty string to use computer name
|
||||
/**
|
||||
* Starts the server on port 8080 (OS X & iOS Simulator) or port 80 (iOS)
|
||||
* using the computer / device name for as the Bonjour name.
|
||||
*
|
||||
* Returns NO if the server failed to start.
|
||||
*/
|
||||
- (BOOL)start;
|
||||
|
||||
/**
|
||||
* Starts the server on a given port and with a specific Bonjour name.
|
||||
* Pass a nil Bonjour name to disable Bonjour entirely or an empty string to
|
||||
* use the computer / device name.
|
||||
*
|
||||
* Returns NO if the server failed to start.
|
||||
*/
|
||||
- (BOOL)startWithPort:(NSUInteger)port bonjourName:(NSString*)name;
|
||||
|
||||
/**
|
||||
* Starts the server with explicit options. This method is the designated way
|
||||
* to start the server.
|
||||
*
|
||||
* Returns NO if the server failed to start.
|
||||
*/
|
||||
- (BOOL)startWithOptions:(NSDictionary*)options;
|
||||
- (void)stop; // Does not abort any currently opened connections
|
||||
|
||||
/**
|
||||
* Stops the server and prevents it to accepts new HTTP requests.
|
||||
*
|
||||
* @warning Stopping the server does not abort GCDWebServerConnection instances
|
||||
* handling already received HTTP requests. These connections will continue to
|
||||
* execute until the corresponding requests and responses are completed.
|
||||
*/
|
||||
- (void)stop;
|
||||
|
||||
@end
|
||||
|
||||
@interface GCDWebServer (Extensions)
|
||||
@property(nonatomic, readonly) NSURL* serverURL; // Only non-nil if server is running
|
||||
@property(nonatomic, readonly) NSURL* bonjourServerURL; // Only non-nil if server is running and Bonjour registration is active
|
||||
|
||||
/**
|
||||
* Returns the server's URL.
|
||||
*
|
||||
* @warning This property is only valid if the server is running.
|
||||
*/
|
||||
@property(nonatomic, readonly) NSURL* serverURL;
|
||||
|
||||
/**
|
||||
* Returns the server's Bonjour URL.
|
||||
*
|
||||
* @warning This property is only valid if the server is running and Bonjour
|
||||
* registration has successfully completed, which can take up to a few seconds.
|
||||
*/
|
||||
@property(nonatomic, readonly) NSURL* bonjourServerURL;
|
||||
|
||||
#if !TARGET_OS_IPHONE
|
||||
|
||||
/**
|
||||
* Runs the server synchronously using -startWithPort:bonjourName: until a
|
||||
* SIGINT signal is received i.e. Ctrl-C. This method is intended to be used
|
||||
* by command line tools.
|
||||
*
|
||||
* Returns NO if the server failed to start.
|
||||
*
|
||||
* @warning This method must be used from the main thread only.
|
||||
*/
|
||||
- (BOOL)runWithPort:(NSUInteger)port bonjourName:(NSString*)name;
|
||||
- (BOOL)runWithOptions:(NSDictionary*)options; // Starts then automatically stops on SIGINT i.e. Ctrl-C (use on main thread only)
|
||||
|
||||
/**
|
||||
* Runs the server synchronously using -startWithOptions: until a SIGINT signal
|
||||
* is received i.e. Ctrl-C. This method is intended to be used by command line
|
||||
* tools.
|
||||
*
|
||||
* Returns NO if the server failed to start.
|
||||
*
|
||||
* @warning This method must be used from the main thread only.
|
||||
*/
|
||||
- (BOOL)runWithOptions:(NSDictionary*)options;
|
||||
|
||||
#endif
|
||||
|
||||
@end
|
||||
|
||||
@interface GCDWebServer (Handlers)
|
||||
|
||||
/**
|
||||
* Adds a default handler to the server to handle all incoming HTTP requests
|
||||
* with a given HTTP method.
|
||||
*/
|
||||
- (void)addDefaultHandlerForMethod:(NSString*)method requestClass:(Class)aClass processBlock:(GCDWebServerProcessBlock)block;
|
||||
- (void)addHandlerForMethod:(NSString*)method path:(NSString*)path requestClass:(Class)aClass processBlock:(GCDWebServerProcessBlock)block; // Path is case-insensitive
|
||||
- (void)addHandlerForMethod:(NSString*)method pathRegex:(NSString*)regex requestClass:(Class)aClass processBlock:(GCDWebServerProcessBlock)block; // Regular expression is case-insensitive
|
||||
|
||||
/**
|
||||
* Adds a handler to the server to handle incoming HTTP requests with a given
|
||||
* HTTP method and a specific case-insensitive path.
|
||||
*/
|
||||
- (void)addHandlerForMethod:(NSString*)method path:(NSString*)path requestClass:(Class)aClass processBlock:(GCDWebServerProcessBlock)block;
|
||||
|
||||
/**
|
||||
* Adds a handler to the server to handle incoming HTTP requests with a given
|
||||
* HTTP method and a path matching a case-insensitive regular expression.
|
||||
*/
|
||||
- (void)addHandlerForMethod:(NSString*)method pathRegex:(NSString*)regex requestClass:(Class)aClass processBlock:(GCDWebServerProcessBlock)block;
|
||||
|
||||
@end
|
||||
|
||||
@interface GCDWebServer (GETHandlers)
|
||||
- (void)addGETHandlerForPath:(NSString*)path staticData:(NSData*)staticData contentType:(NSString*)contentType cacheAge:(NSUInteger)cacheAge; // Path is case-insensitive
|
||||
- (void)addGETHandlerForPath:(NSString*)path filePath:(NSString*)filePath isAttachment:(BOOL)isAttachment cacheAge:(NSUInteger)cacheAge allowRangeRequests:(BOOL)allowRangeRequests; // Path is case-insensitive
|
||||
- (void)addGETHandlerForBasePath:(NSString*)basePath directoryPath:(NSString*)directoryPath indexFilename:(NSString*)indexFilename cacheAge:(NSUInteger)cacheAge allowRangeRequests:(BOOL)allowRangeRequests; // Base path is recursive and case-sensitive
|
||||
|
||||
/**
|
||||
* Adds a handler to the server to respond to incoming "GET" HTTP requests
|
||||
* with a specific case-insensitive path with in-memory data.
|
||||
*/
|
||||
- (void)addGETHandlerForPath:(NSString*)path staticData:(NSData*)staticData contentType:(NSString*)contentType cacheAge:(NSUInteger)cacheAge;
|
||||
|
||||
/**
|
||||
* Adds a handler to the server to respond to incoming "GET" HTTP requests
|
||||
* with a specific case-insensitive path with a file.
|
||||
*/
|
||||
- (void)addGETHandlerForPath:(NSString*)path filePath:(NSString*)filePath isAttachment:(BOOL)isAttachment cacheAge:(NSUInteger)cacheAge allowRangeRequests:(BOOL)allowRangeRequests;
|
||||
|
||||
/**
|
||||
* Adds a handler to the server to respond to incoming "GET" HTTP requests
|
||||
* with a case-insensitive path inside a base path with the corresponding file
|
||||
* inside a local directory. If no local file matches the request path, a 401
|
||||
* HTTP status code is returned to the client.
|
||||
*
|
||||
* The "indexFilename" argument allows to specify an "index" file name to use
|
||||
* when the request path corresponds to a directory.
|
||||
*/
|
||||
- (void)addGETHandlerForBasePath:(NSString*)basePath directoryPath:(NSString*)directoryPath indexFilename:(NSString*)indexFilename cacheAge:(NSUInteger)cacheAge allowRangeRequests:(BOOL)allowRangeRequests;
|
||||
|
||||
@end
|
||||
|
||||
@interface GCDWebServer (Logging)
|
||||
|
||||
#ifndef __GCDWEBSERVER_LOGGING_HEADER__
|
||||
+ (void)setLogLevel:(GCDWebServerLogLevel)level; // Default level is DEBUG or INFO if "NDEBUG" is defined when building (it can also be set at runtime with the "logLevel" environment variable)
|
||||
|
||||
/**
|
||||
* Sets the current log level below which logged messages are discarded.
|
||||
*
|
||||
* The default level is either DEBUG or INFO if "NDEBUG" is defined at build-time.
|
||||
* It can also be set at runtime with the "logLevel" environment variable.
|
||||
*/
|
||||
+ (void)setLogLevel:(GCDWebServerLogLevel)level;
|
||||
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Logs a message with the kGCDWebServerLogLevel_Verbose level.
|
||||
*/
|
||||
- (void)logVerbose:(NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
|
||||
|
||||
/**
|
||||
* Logs a message with the kGCDWebServerLogLevel_Info level.
|
||||
*/
|
||||
- (void)logInfo:(NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
|
||||
|
||||
/**
|
||||
* Logs a message with the kGCDWebServerLogLevel_Warning level.
|
||||
*/
|
||||
- (void)logWarning:(NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
|
||||
|
||||
/**
|
||||
* Logs a message with the kGCDWebServerLogLevel_Error level.
|
||||
*/
|
||||
- (void)logError:(NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
|
||||
|
||||
@end
|
||||
|
||||
#ifdef __GCDWEBSERVER_ENABLE_TESTING__
|
||||
|
||||
@interface GCDWebServer (Testing)
|
||||
@property(nonatomic, getter=isRecordingEnabled) BOOL recordingEnabled; // Creates files in the current directory containing the raw data for all requests and responses (directory most NOT contain prior recordings)
|
||||
- (NSInteger)runTestsWithOptions:(NSDictionary*)options inDirectory:(NSString*)path; // Returns number of failed tests or -1 if server failed to start
|
||||
|
||||
/**
|
||||
* Activates recording of HTTP requests and responses which create files in the
|
||||
* current directory containing the raw data for all requests and responses.
|
||||
*
|
||||
* @warning The current directory must not contain any prior recording files.
|
||||
*/
|
||||
@property(nonatomic, getter=isRecordingEnabled) BOOL recordingEnabled;
|
||||
|
||||
/**
|
||||
* Runs tests by playing back pre-recorded HTTP requests in the given directory
|
||||
* and comparing the generated responses with the pre-recorded ones.
|
||||
*
|
||||
* Returns the number of failed tests or -1 if server failed to start.
|
||||
*/
|
||||
- (NSInteger)runTestsWithOptions:(NSDictionary*)options inDirectory:(NSString*)path;
|
||||
|
||||
@end
|
||||
|
||||
#endif
|
||||
|
||||
Reference in New Issue
Block a user