CaffeineHTTPProxy

@objc final public class CaffeineHTTPProxy : NSObject, GCDAsyncUdpSocketDelegate

CaffeineHTTPProxy hooks into the iOS URL loading system to accelerate the network requests you specify using allow: and deny:.

The Caffeine API consists of 3 main functions: start, allow:, and deny:

This class is packaged inside the Proxeine module, so it must be imported into your App Delegate.

To a Swift project:

    import Proxeine

To an Objective-C Project:

    import "Proxeine-Swift.h"

By Default, Caffeine is added to all instances of NSURLSessionConfiguration.defaultSessionConfiguration().

Caffeine will work alongside networking libraries such as Alamofire or AFNetworking.

This class uses the open source CocoaAsyncSocket library’s GCDAsyncUdpSocketDelegate protocol for frictionless UDP-diagnostic logging.

Note

If at any time you require help, please contact our engineers at help@caffei.net

Warning

NSURLSessions that do not use NSURLSession.sharedSession() or the NSURLSessionConfiguration.defaultSessionConfiguration should call addCaffeine on their session configurations.

  • This is the name of a notification posted to the default notification center after Caffeine has received its remote configuration file. The userInfo dictionary of the notification contains the boolean value of whether or not the current session is using Caffeine keyed by this same notification name. This can be used to track whether the current session uses Caffeine or not.

    A Swift 3 in a View Controller:

    import UIKit
    import Proxeine
    
    class ViewController: UIViewController {
    
        override func viewDidLoad() {
            super.viewDidLoad()
            NotificationCenter.default.addObserver(self, selector: #selector(receivedCaffeineNotification(aNotification:)), name: NSNotification.Name(rawValue: CaffeineHTTPProxy.caffeineInformationStringNotificationKey), object: nil)
        }
    
        // Our method to receive the Caffeine notification
        func receivedCaffeineNotification(aNotification: NSNotification) {
            if aNotification.name.rawValue == CaffeineHTTPProxy.caffeineInformationStringNotificationKey {
                if let usingCaffeine = aNotification.userInfo?[CaffeineHTTPProxy.caffeineInformationStringNotificationKey] as? Bool {
                    // 'usingCaffeine` now tracks whether Caffeine is enabled for this SESSION
                    // You can log this value with your analytics service
                }
            }
        }
    
        deinit {
            NotificationCenter.default.removeObserver(self)
        }
    }
    

    A Swift 2 example in an App Delegate:

    import UIKit
    import Proxeine
    
    @UIApplicationMain
    class AppDelegate: UIResponder, UIApplicationDelegate {
    
        var window: UIWindow?
    
        func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
            CaffeineHTTPProxy.allow("http://google.com/")
            CaffeineHTTPProxy.start()
    
            // Start listening for the Caffeine notification
    
            NSNotificationCenter.defaultCenter().addObserver(self, selector: #selector(AppDelegate.receivedCaffeineNotification(_:)), name: CaffeineHTTPProxy.caffeineInformationStringNotificationKey, object: nil)
                return true
        }
    
    
        // Our method to receive the Caffeine notification
        // Called after downloading the percentage value from a remote server
            func receivedCaffeineNotification(aNotification: NSNotification) {
            if aNotification.name == CaffeineHTTPProxy.caffeineInformationStringNotificationKey {
                if let usingCaffeine = aNotification.userInfo?[CaffeineHTTPProxy.caffeineInformationStringNotificationKey] as? Bool {
                    // 'usingCaffeine` now tracks whether Caffeine is enabled for this SESSION
                    // Log this value to your 3rd party analytics service
                }
            }
        }
    }
    
    

    Declaration

    Swift

    public static let caffeineInformationStringNotificationKey = "CaffeineInformationStringNotificationKey"
  • Starts Caffeine. start should be called first in your App Delegate’s application:didFinishLaunchingWithOptions: function.

    By default, no requests are Caffeinated. To Caffeinate a request, it must be explicitly allowed using allow:.

    Swift 3:

    import Proxeine
    func applicationDidFinishLaunching(_ application: UIApplication) {
       CaffeineHTTPProxy.start()
       //enter `allow` and `deny` filters here
    }
    

    Swift 2.3:

       import Proxeine
       func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
           CaffeineHTTPProxy.start()
           //enter `allow` and `deny` filters here
       }
    

    Objective-C:

       import "Proxeine-Swift.h"
       - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
           [CaffeineHTTPProxy start];
           //enter `allow` and `deny` filters here
       }
    

    Warning

    Calling this function twice is undefined.

    Complexity

    This function is asynchronous and returns immediately.

    See also

    allow:, deny:

    Declaration

    Swift

    public static func start()
  • Calling start and in debug mode will print additional information to the console about Caffeine for debugging purposes.

    Declaration

    Swift

    public static func start(debug: Bool)

    Parameters

    debug

    Whether or not to start Caffeine in debug mode

  • allow: Caffeinates specific URLs or sets of URLs. No requests will be proxied unless their URL is allowed. Call allow inside your AppDelegate, within the application:didFinishLaunchingWithOptions: function.

    Swift:

        CaffeineHTTPProxy.allow("*.png")
        CaffeineHTTPProxy.allow("https://google.com*")
        CaffeineHTTPProxy.allow("http:*")
        CaffeineHTTPProxy.allow("http://google.com/humans.txt")
    

    Objective-C:

       [CaffeineHTTPProxy allow:@"*.png"];
       [CaffeineHTTPProxy allow:@"https://google.com*"];
       [CaffeineHTTPProxy allow:@"http:*"];
       [CaffeineHTTPProxy allow:@"http://google.com/humans.txt"];
    

    This allow configurations (above) specify that the following will be Caffeinated:

    Declaration

    Swift

    public static func allow(_ path: String)
  • deny: Decaffeinates specific URLs or sets of URLs. deny overrides allow. No requests will be proxied if their URL is within a deny clause. Call deny inside your AppDelegate, within the application:didFinishLaunchingWithOptions: function.

    Swift:

    CaffeineHTTPProxy.deny("*.png")
    CaffeineHTTPProxy.deny("https://google.com*")
    CaffeineHTTPProxy.deny("http:*")
    CaffeineHTTPProxy.deny("http://google.com/humans.txt")
    

    Objective-C:

    [CaffeineHTTPProxy deny:@"*.png"];
    [CaffeineHTTPProxy deny:@"https://google.com*"];
    [CaffeineHTTPProxy deny:@"http:*"];
    [CaffeineHTTPProxy deny:@"http://google.com/humans.txt"];
    

    This deny configuration (above) specify that the following will NOT be Caffeinated:

    Declaration

    Swift

    public static func deny(_ path: String)
  • Decaffeinates specific requests by conditioning on their HTTP methods. Call deny inside your AppDelegate, within the application:didFinishLaunchingWithOptions: function before start(). By default, all HTTP methods are allowed.

    Swift:

    CaffeineHTTPProxy.deny(.HEAD)
    CaffeineHTTPProxy.deny(.CONNECT)
    

    Requests with their httpMethod set to HEAD or CONNECT will not use Caffeine.

    Declaration

    Swift

    public static func deny(_ httpMethod: HTTPMethod)
  • By default, Caffeine will log whether or not Caffeine was used for a request, request URLs, HTTP methods, and response times to console. Calling this method will cause the console to cease this logging.

    Declaration

    Swift

    public static func silenceRequestLogging()