Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/marcuswestin/WebViewProxy

A standalone iOS & OSX class for intercepting and proxying HTTP requests (e.g. from a Web View)
https://github.com/marcuswestin/WebViewProxy
Last synced: about 2 months ago
JSON representation
A standalone iOS & OSX class for intercepting and proxying HTTP requests (e.g. from a Web View)
Host: GitHub
URL: https://github.com/marcuswestin/WebViewProxy
Owner: marcuswestin
License: mit
Created: 2012-10-01T05:28:15.000Z (about 12 years ago)
Default Branch: master
Last Pushed: 2017-02-24T09:11:13.000Z (almost 8 years ago)
Last Synced: 2024-10-13T00:54:44.707Z (2 months ago)
Language: Objective-C
Homepage: https://twitter.com/marcuswestin
Size: 234 KB
Stars: 864
Watchers: 38
Forks: 120
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: Changelog
- License: LICENSE
Awesome Lists containing this project

README

        WebViewProxy

============

Proxy requests for a web views, easily and without mucking around with NSURLProtocol.

Works on iOS and OSX.

Responses to intercepted requests may be served either synchronously or asynchronously - this stands in contrast to the `UIWebViewDelegate` method `-(NSCachedURLResponse *)cachedResponseForRequest:url:host:path:`, which may only intercept requests and serve responses synchronously (making it impossible to e.g. proxy requests through to the network without blocking on the network request).

If you like WebViewProxy you should also check out [WebViewJavascriptBridge](https://github.com/marcuswestin/WebViewJavascriptBridge).

API

---

### 1: Register handlers with `WebViewProxy` to intercept requests

##### + (void) handleRequestsWithScheme:(NSString\*)scheme handler:(WVPHandler)handler;

Intercept all UIWebView requests with the given scheme.

Examples:

```objc

[WebViewProxy handleRequestsWithScheme:@"my_custom_scheme" handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

```

##### + (void) handleRequestsWithHost:(NSString\*)host handler:(WVPHandler)handler;

Intercept all UIWebView requests with the given host.

Examples

```objc

[WebViewProxy handleRequestsWithHost:@"foo" handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

```

##### + (void) handleRequestsWithHost:(NSString\*)host path:(NSString\*)path handler:(WVPHandler)handler;

Intercept all UIWebView requests matching the given host and URL path.

Examples

```objc

[WebViewProxy handleRequestsWithHost:@"foo.com" path:@"/bar" handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

```

##### + (void) handleRequestsWithHost:(NSString\*)host pathPrefix:(NSString\*)pathPrefix handler:(WVPHandler)handler;

Intercept all UIWebView requests matching the given host and URL path prefix.

For example, a handler registered with `[WebViewProxy handleRequestsWithHost:@"foo.com" pathPrefix:@"/bar" handler:...]` will intercept requests for `http://foo.com/bar`, `https://foo.com/bar/cat?wee=yes`, `http://foo.com/bar/arbitrarily/long/subpath`, etc.

Examples

```objc

[WebViewProxy handleRequestsWithHost:@"foo.com" pathPrefix:@"/bar" handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

```

##### + (void) handleRequestsMatching:(NSPredicate\*)predicate handler:(WVPHandler)handler;

Intercept all UIWebView requests where the `NSURL` matches the given `NSPredicate`.

Examples

```objc

[WebViewProxy handleRequestsMatching:[NSPredicate predicateWithFormat:@"absoluteString MATCHES[cd] '^http:'"] handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

[WebViewProxy handleRequestsMatching:[NSPredicate predicateWithFormat:@"host MATCHES[cd] '[foo|bar]'"]  handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

```

### 2: Respond through the `WVPResponse`

All registered handlers are given a `WVPRespone* res`. You respond to the request by calling methods on this object.

There are 3 type of APIs for responding to a request

- High level API for responding with an image, text, html or json

- Low level API for responding with specific HTTP headers and NSData

- Piping API for passing data/errors from `NSURLConnection` through the `WVPResponse`

#### High level response API

Descriptions and examples will be fleshed out.

##### - (void) respondWithImage:(UIImage\*)image;

Respond with an image (sent with Content-Type "image/png" by default, or "image/jpg" for requests that end in `.jpg` or `.jpeg`):

Examples

```objc

[WebViewProxy handleRequestsWithHost:@"imageExample" path:@"GoogleLogo.png" handler:^(NSURLRequest* req, WVPResponse *res) {

	UIImage* image = [UIImage imageNamed:@"GoogleLogo.png"];

	[res respondWithImage:image];

}];

```

##### - (void) respondWithImage:(UIImage\*)image mimeType:(NSString*)mimeType;

Respond with an image and the given mime type.

Examples

```objc

[WebViewProxy handleRequestsWithHost:@"imageExample" handler:^(NSURLRequest* req, WVPResponse *res) {

	UIImage* image = [UIImage imageNamed:@"GoogleLogo.png"];

	[res respondWithImage:image mimeType:@"image/png"];

}];

```

##### - (void) respondWithText:(NSString\*)text;

Respond with a text response (sent with Content-Type "text/plain"):

```objc

[WebViewProxy handleRequestsWithHost:@"textExample" handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"Hi!"];

}];

```

##### - (void) respondWithHTML:(NSString\*)html;

Respond with HTML (sent with Content-Type "text/html"):

```objc

[WebViewProxy handleRequestsWithHost:@"htmlExample" handler:^(NSURLRequest* req, WVPResponse *res) {

	[res respondWithText:@"
Hi!"];

}];

```

##### - (void) respondWithJSON:(NSDictionary\*)jsonObject;

Respond with JSON (sent with Content-Type "application/json"):

```objc

[WebViewProxy handleRequestsWithHost:@"textExample" handler:^(NSURLRequest* req, WVPResponse *res) {

	NSDictionary* jsonObject = [NSDictionary dictionaryWithObject:@"foo" forKey:@"bar"];

	[res respondWithJSON:jsonObject]; // sends '{ "bar":"foo" }'

}];

```

#### Low level response API

Descriptions and examples will be fleshed out.

##### - (void) respondWithStatusCode:(NSInteger)statusCode text:(NSString\*)text;

Respond with the given HTTP status code and text.

Examples

```objc

[res respondWithStatusCode:400 text:@"Bad request"];

[res respondWithStatusCode:404 text:@"Not found"];

```

##### - (void) setHeader:(NSString\*)headerName value:(NSString\*)headerValue;

Set a response header before responding.

Examples

```objc

[res setHeader:@"Content-Type" value:@"image/gif"];

[res setHeader:@"Content-Type" value:@"audio/wav"];

[res setHeader:@"Host" value:@"WebViewProxy"];

```

##### - (void) setHeaders:(NSDictionary*)headers;

Set multiple response headers before responding.

Examples

```objc

[res setHeaders:@{ @"Content-Type":@"image/gif", @"Host":@"WebViewProxy" }];

```

##### - (void) respondWithData:(NSData\*)data mimeType:(NSString\*)mimeType;

Respond with the given data and mime type (the mime type gets sent as the HTTP header `Content-Type`).

If mimeType is nil, WebWiewProxy attempts to infer it from the request URL path extension.

Examples

```objc

NSString* greeting = @"Hi!";

NSData* data = [greeting dataUsingEncoding:NSUTF8StringEncoding];

[res respondWithData:data mimeType:@"text/plain"];

```

##### - (void) respondWithData:(NSData\*)data mimeType:(NSString\*)mimeType statusCode:(NSInteger)statusCode;

Respond with the given data, mime type and HTTP status code (the mime type gets sent as the HTTP header `Content-Type`).

If mimeType is nil, WebWiewProxy attempts to infer it from the request URL path extension.

Examples

```objc

NSData* data = [@"
Item has been created" dataUsingEncoding:NSUTF8StringEncoding];

[res respondWithData:data mimeType:@"text/html" statusCode:201];

[res respondWithData:nil mimeType:nil statusCode:304]; // HTTP status code 304 "Not modified"

[res respondWithData:nil mimeType:nil statusCode:204]; // HTTP status code 204 "No Content"

```

##### NSURLCacheStoragePolicy cachePolicy (property)

The cache policy for the response. Default value is `NSURLCacheStorageNotAllowed`

Examples

```objc

response.cachePolicy = NSURLCacheStorageAllowed;

response.cachePolicy = NSURLCacheStorageAllowedInMemoryOnly;

response.cachePolicy = NSURLCacheStorageNotAllowed;

```

#### Proxy requests to remote servers

There are many ways to proxy remote requests with `WebViewProxy`.

The easiest approach uses `WebViewProxyResponse` as a `NSURLConnection` delegate. This pipes the response through the proxy response:

```objc

[WebViewProxy handleRequestsWithHost:@"example.proxy" handler:^(NSURLRequest *req, WVPResponse *res) {

    NSString* proxyUrl = [req.URL.absoluteString stringByReplacingOccurrencesOfString:@"example.proxy" withString:@"example.com"];

    NSURLRequest* proxyReq = [NSURLRequest requestWithURL:[NSURL URLWithString:proxyUrl]];

    [NSURLConnection connectionWithRequest:proxyReq delegate:res];

}];

```

Another approach which gives you more control but reads the entire response into memory:

```objc

[WebViewProxy handleRequestsWithHost:@"example.proxy" handler:^(NSURLRequest *req, WVPResponse *res) {

    NSString* proxyUrl = [req.URL.absoluteString stringByReplacingOccurrencesOfString:@"example.proxy" withString:@"example.com"];

    NSURLRequest* proxyReq = [NSURLRequest requestWithURL:[NSURL URLWithString:proxyUrl]];

    NSOperationQueue* queue = [NSOperationQueue new];

    [NSURLConnection sendAsynchronousRequest:proxyReq queue:queue completionHandler:^(NSURLResponse* proxyRes, NSData* proxyData, NSError* proxyErr) {

        if (proxyErr) {

            return [res pipeError:proxyErr];

        } else {

            NSInteger statusCode = [(NSHTTPURLResponse*)proxyRes statusCode];

            [res setHeaders:[(NSHTTPURLResponse*)proxyRes allHeaderFields]];

            [res respondWithData:proxyData mimeType:proxyRes.MIMEType statusCode:statusCode];

        }

    }];

}];

```

#### Piping response API

Pipe an `NSURLResponse` and its data into the `WVPResponse`. This makes it simple to e.g. proxy a request and its response through an NSURLConnection.

Examples to be written.

##### - (void) pipeResponse:(NSURLResponse\*)response;

Pipe an NSURLResponse into the response.

##### - (void) pipeData:(NSData\*)data;

Pipe data into the response.

##### - (void) pipeError:(NSError\*)error;

Pipe an error into the response (e.g a network error).

##### - (void) pipeEnd;

Finish a piped response.

### 3: (optional) Handle "Stop Loading" event

A request handler may be told to "stop loading". This can happen e.g as a result of `cancel:` being called on the underlying `NSURLRequest`. You can get notified of this via the `handleStopLoadingRequest:` method on `WVPResponse`.

This API can be used to e.g stop performing an expensive computation in your request handler.

Examples

```objc

[WebViewProxy handleRequestsMatching:predicate handler:^(NSURLRequest* req, WVPResponse *res) {

    NSOperation* expensiveOperation = [self startExpensiveOperation];

    [res handleStopLoadingRequest:^{

        [expensiveOperation cancel]

    }];

}];

```