Update README and CONTRIBUTING to Markdown and new documentation. (#432)

Contributing.md → CONTRIBUTING.md

@@ -1,9 +1,5 @@
 # Contributing to SocketRocket
-We want to make contributing to this project as easy and transparent as
-possible.
-
-## Our Development Process
-... (in particular how this is synced with internal changes to the project)
+We want to make contributing to this project as easy and transparent as possible.
 
 ## Pull Requests
 We actively welcome your pull requests.
@@ -16,8 +12,8 @@ We actively welcome your pull requests.
 6. If you haven't already, complete the Contributor License Agreement ("CLA").
 
 ## Contributor License Agreement ("CLA")
-In order to accept your pull request, we need you to submit a CLA. You only need
-to do this once to work on any of Facebook's open source projects.
+In order to accept your pull request, we need you to submit a CLA. 
+You only need to do this once to work on any of Facebook's open source projects.
 
 Complete your CLA here: <https://code.facebook.com/cla>
 
@@ -34,5 +30,4 @@ outlined on that page and do not file a public issue.
 * Try to keep lines under 140 characters, if possible.
 
 ## License
-By contributing to SocketRocket, you agree that your contributions will be licensed
-under its BSD license.
+By contributing to SocketRocket, you agree that your contributions will be licensed under its BSD license.

README.md

@@ -0,0 +1,213 @@
+# SocketRocket
+
+![Platforms][platforms-svg]
+[![License][license-svg]][license-link]
+
+[![Podspec][podspec-svg]][podspec-link]
+[![Carthage Compatible][carthage-svg]](carthage-link)
+
+[![Build Status][build-status-svg]][build-status-link]
+
+A conforming WebSocket ([RFC 6455](https://tools.ietf.org/html/rfc6455>)) client library for iOS, macOS and tvOS.
+
+Test results for SocketRocket [here](http://facebook.github.io/SocketRocket/results/).
+You can compare to what modern browsers look like [here](http://autobahn.ws/testsuite/reports/clients/index.html).
+
+SocketRocket currently conforms to all core ~300 of [Autobahn](http://autobahn.ws/testsuite/>)'s fuzzing tests 
+(aside from two UTF-8 ones where it is merely *non-strict* tests 6.4.2 and 6.4.4).
+
+## Features/Design
+
+- TLS (wss) support, including self-signed certificates.
+- Seems to perform quite well.
+- Supports HTTP Proxies.
+- Supports IPv4/IPv6.
+- Supports SSL certificate pinning.
+- Sends `ping` and can process `pong` events.
+- Asynchronous and non-blocking. Most of the work is done on a background thread.
+- Supports iOS, macOS, tvOS.
+
+## Installing
+
+There are a few options. Choose one, or just figure it out:
+
+- **[CocoaPods](https://cocoapods.org)**
+
+ Add the following line to your Podfile:
+ ```ruby
+ pod 'SocketRocket'
+ ```
+ Run `pod install`, and you are all set.
+  
+- **[Carthage](https://github.com/carthage/carthage)**
+
+ Add the following line to your Cartfile:
+ ```
+ github "facebook/SocketRocket"
+ ```
+ Run `carthage update`, and you should now have the latest version of `SocketRocket` in your `Carthage` folder.
+
+- **Using SocketRocket as a sub-project**
+
+  You can also include `SocketRocket` as a subproject inside of your application if you'd prefer, although we do not recommend this, as it will increase your indexing time significantly. To do so, just drag and drop the `SocketRocket.xcodeproj` file into your workspace.
+
+## API
+
+### `SRWebSocket`
+
+The Web Socket.
+
+#### Note:
+
+`SRWebSocket` will retain itself between `-(void)open` and when it closes, errors, or fails.
+This is similar to how `NSURLConnection` behaves (unlike `NSURLConnection`, `SRWebSocket` won't retain the delegate).
+
+#### Interface
+
+```objective-c
+@interface SRWebSocket : NSObject
+
+// Make it with this
+- (instancetype)initWithURLRequest:(NSURLRequest *)request;
+
+// Set this before opening
+@property (nonatomic, weak) id <SRWebSocketDelegate> delegate;
+
+// Open with this
+- (void)open;
+
+// Close it with this
+- (void)close;
+
+// Send a Data
+- (void)sendData:(nullable NSData *)data error:(NSError **)error;
+
+// Send a UTF8 String
+- (void)sendString:(NSString *)string error:(NSError **)error;
+
+@end
+```
+
+### `SRWebSocketDelegate`
+
+You implement this
+
+```objective-c
+@protocol SRWebSocketDelegate <NSObject>
+
+@optional
+
+- (void)webSocketDidOpen:(SRWebSocket *)webSocket;
+
+- (void)webSocket:(SRWebSocket *)webSocket didReceiveMessageWithString:(NSString *)string;
+- (void)webSocket:(SRWebSocket *)webSocket didReceiveMessageWithData:(NSData *)data;
+
+- (void)webSocket:(SRWebSocket *)webSocket didFailWithError:(NSError *)error;
+- (void)webSocket:(SRWebSocket *)webSocket didCloseWithCode:(NSInteger)code reason:(nullable NSString *)reason wasClean:(BOOL)wasClean;
+
+@end
+```
+
+## Testing
+
+Included are setup scripts for the python testing environment.
+It comes packaged with vitualenv so all the dependencies are installed in userland.
+
+To run the short test from the command line, run:
+```bash
+  make test
+```
+
+To run all the tests, run:
+```bash
+  make test_all
+```
+
+The short tests don't include the performance tests
+(the test harness is actually the bottleneck, not SocketRocket).
+
+The first time this is run, it may take a while to install the dependencies. It will be smooth sailing after that. 
+
+You can also run tests inside Xcode, which runs the same thing, but makes it easier to debug.
+
+- Choose the `SocketRocket` target
+- Run the test action (`⌘+U`)
+
+### TestChat Demo Application
+
+SocketRocket includes a demo app, TestChat.
+It will "chat" with a listening websocket on port 9900.
+
+#### TestChat Server
+
+The sever takes a message and broadcasts it to all other connected clients.
+
+It requires some dependencies though to run. 
+We also want to reuse the virtualenv we made when we ran the tests. 
+If you haven't run the tests yet, go into the SocketRocket root directory and type:
+
+```bash
+make test
+```
+
+This will set up your [virtualenv](https://pypi.python.org/pypi/virtualenv).
+
+Now, in your terminal:
+
+```bash
+source .env/bin/activate
+pip install git+https://github.com/tornadoweb/tornado.git
+```
+
+In the same terminal session, start the chatroom server:
+
+```bash
+python TestChatServer/py/chatroom.py
+```
+
+There's also a Go implementation (with the latest weekly) where you can:
+
+```bash
+cd TestChatServer/go
+go run chatroom.go
+```
+
+#### Chatting
+
+Now, start TestChat.app (just run the target in the Xcode project).
+If you had it started already you can hit the refresh button to reconnect.
+It should say "Connected!" on top.
+
+To talk with the app, open up your browser to [http://localhost:9000](http://localhost:9000) and start chatting.
+
+
+## WebSocket Server Implementation Recommendations
+
+SocketRocket has been used with the following libraries:
+
+- [Tornado](https://github.com/tornadoweb/tornado)
+- Go's [WebSocket package](https://godoc.org/golang.org/x/net/websocket) or Gorilla's [version](http://www.gorillatoolkit.org/pkg/websocket).
+- [Autobahn](http://autobahn.ws/testsuite/) (using its fuzzing client).
+
+The Tornado one is dirt simple and works like a charm. 
+([IPython notebook](http://ipython.org/ipython-doc/dev/interactive/htmlnotebook.html) uses it too).
+It's much easier to configure handlers and routes than in Autobahn/twisted.
+
+## Contributing
+
+We’re glad you’re interested in SocketRocket, and we’d love to see where you take it. 
+Please read our [contributing guidelines](https://github.com/facebook/SocketRocket/blob/master/CONTRIBUTING.md) prior to submitting a Pull Request.
+
+ [build-status-svg]: https://img.shields.io/travis/facebook/SocketRocket/master.svg
+ [build-status-link]: https://travis-ci.org/facebook/SocketRocket/branches
+
+ [license-svg]: https://img.shields.io/badge/license-BSD-lightgrey.svg
+ [license-link]: https://github.com/BoltsFramework/SocketRocket/blob/master/LICENSE
+
+ [podspec-svg]: https://img.shields.io/cocoapods/v/SocketRocket.svg
+ [podspec-link]: https://cocoapods.org/pods/SocketRocket
+ 
+ [carthage-svg]: https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat
+ [carthage-link]: https://github.com/carthage/carthage
+
+ [platforms-svg]: http://img.shields.io/cocoapods/p/SocketRocket.svg?style=flat

README.rst

@@ -1,246 +0,0 @@
-SocketRocket Objective-C WebSocket Client (beta)
-================================================
-A conforming WebSocket (`RFC 6455 <https://tools.ietf.org/html/rfc6455>`_)
-client library.
-
-`Test results for SocketRocket here <http://facebook.github.io/SocketRocket/results/>`_.
-You can compare to what `modern browsers look like here
-<http://autobahn.ws/testsuite/reports/clients/index.html>`_.
-
-SocketRocket currently conforms to all ~300 of `Autobahn
-<http://autobahn.ws/testsuite/>`_'s fuzzing tests (aside from
-two UTF-8 ones where it is merely *non-strict*. tests 6.4.2 and 6.4.4)
-
-Features/Design
----------------
-- TLS (wss) support.  It uses CFStream so we get this for *free*
-- Uses NSStream/CFNetworking.  Earlier implementations used ``dispatch_io``,
-  however, this proved to be make TLS nearly impossible.  Also I wanted this to
-  work in iOS 4.x. (SocketRocket only supports 5.0 and above now)
-- Uses ARC.  It uses the 4.0 compatible subset (no weak refs).
-- Seems to perform quite well
-- Parallel architecture. Most of the work is done in background worker queues.
-- Delegate-based. Had older versions that could use blocks too, but I felt it
-  didn't blend well with retain cycles and just objective C in general.
-
-Changes
--------
-
-v0.3.1-beta2 - 2013-01-12
-`````````````````````````
-
-- Stability fix for ``closeWithCode:reason:`` (Thanks @michaelpetrov!)
-- Actually clean up the NSStreams and remove them from their runloops
-- ``_SRRunLoopThread``'s ``main`` wasn't correctly wrapped with
-  ``@autoreleasepool``
-
-v0.3.1-beta1 - 2013-01-12
-`````````````````````````
-
-- Cleaned up GCD so OS_OBJECT_USE_OBJC_RETAIN_RELEASE is optional
-- Removed deprecated ``dispatch_get_current_queue`` in favor of ``dispatch_queue_set_specific`` and ``dispatch_get_specific``
-- Dropping support for iOS 4.0 (it may still work)
-
-
-Installing (iOS)
-----------------
-There's a few options. Choose one, or just figure it out
-
-- You can copy all the files in the SocketRocket group into your app.
-- Include SocketRocket as a subproject and use libSocketRocket
-
-  If you do this, you must add -ObjC to your "other linker flags" option
-
-- For OS X you will have to repackage make a .framework target.  I will take
-  contributions. Message me if you are interested.
-
-
-Depending on how you configure your project you may need to ``#import`` either
-``<SocketRocket/SRWebSocket.h>`` or ``"SRWebSocket.h"``
-
-Framework Dependencies
-``````````````````````
-Your .app must be linked against the following frameworks/dylibs
-
-- libicucore.dylib
-- CFNetwork.framework
-- Security.framework
-- Foundation.framework
-
-Installing (OS X)
------------------
-SocketRocket now has (64-bit only) OS X support.  ``SocketRocket.framework``
-inside Xcode project is for OS X only.  It should be identical in function aside
-from the unicode validation.  ICU isn't shipped with OS X which is what the
-original implementation used for unicode validation.  The workaround is much
-more rudimentary and less robust.
-
-1. Add SocketRocket.xcodeproj as either a subproject of your app or in your workspace.
-2. Add ``SocketRocket.framework`` to the link libraries
-3. If you don't have a "copy files" step for ``Framework``, create one
-4. Add ``SocketRocket.framework`` to the "copy files" step.
-
-API
----
-The classes
-
-``SRWebSocket``
-```````````````
-The Web Socket.
-
-.. note:: ``SRWebSocket`` will retain itself between ``-(void)open`` and when it
-  closes, errors, or fails.  This is similar to how ``NSURLConnection`` behaves.
-  (unlike ``NSURLConnection``, ``SRWebSocket`` won't retain the delegate)
-
-What you need to know
-
-.. code-block:: objective-c
-
-  @interface SRWebSocket : NSObject
-
-  // Make it with this
-  - (id)initWithURLRequest:(NSURLRequest *)request;
-
-  // Set this before opening
-  @property (nonatomic, assign) id <SRWebSocketDelegate> delegate;
-
-  - (void)open;
-  
-  // Close it with this
-  - (void)close;
-
-  // Send a UTF8 String or Data
-  - (void)send:(id)data;
-
-  @end
-
-``SRWebSocketDelegate``
-```````````````````````
-You implement this
-
-.. code-block:: objective-c
-
-  @protocol SRWebSocketDelegate <NSObject>
-
-  - (void)webSocket:(SRWebSocket *)webSocket didReceiveMessage:(id)message;
-
-  @optional
-
-  - (void)webSocketDidOpen:(SRWebSocket *)webSocket;
-  - (void)webSocket:(SRWebSocket *)webSocket didFailWithError:(NSError *)error;
-  - (void)webSocket:(SRWebSocket *)webSocket didCloseWithCode:(NSInteger)code reason:(NSString *)reason wasClean:(BOOL)wasClean;
-
-  @end
-
-Known Issues/Server Todo's
---------------------------
-- Needs auth delegates (like in NSURLConnection)
-- Move the streams off the main runloop (most of the work is backgrounded uses
-  GCD, but I just haven't gotten around to moving it off the main loop since I
-  converted it from dispatch_io)
-- Re-implement server. I removed an existing implementation as well because it
-  wasn't being used and I wasn't super happy with the interface.  Will revisit
-  this.
-- Separate framer and client logic. This will make it nicer when having a
-  server.
-
-Testing
--------
-Included are setup scripts for the python testing environment.  It comes
-packaged with vitualenv so all the dependencies are installed in userland.
-
-To run the short test from the command line, run::
-
-  make test
-
-To run all the tests, run::
-
-  make test_all
-
-The short tests don't include the performance tests.  (the test harness is
-actually the bottleneck, not SocketRocket).
-
-The first time this is run, it may take a while to install the dependencies.  It
-will be smooth sailing after that.  After the test runs the makefile will open
-the results page in your browser.  If nothing comes up, you failed.  Working on
-making this interface a bit nicer.
-
-To run from the app, choose the ``SocketRocket`` target and run the test action
-(``cmd+u``). It runs the same thing, but makes it easier to debug.  There is
-some serious pre/post hooks in the Test action.  You can edit it to customize
-behavior.
-
-.. note:: Xcode only up to version 4.4 is currently supported for the test
-  harness
-
-TestChat Demo Application
--------------------------
-SocketRocket includes a demo app, TestChat.  It will "chat" with a listening
-websocket on port 9900.
-
-It's a simple project.  Uses storyboard.  Storyboard is sweet.
-
-
-TestChat Server
-```````````````
-We've included a small server for the chat app.  It has a simple function.
-It will take a message and broadcast it to all other connected clients.
-
-We have to get some dependencies.  We also want to reuse the virtualenv we made
-when we ran the tests. If you haven't run the tests yet, go into the
-SocketRocket root directory and type::
-
-  make test
-
-This will set up your `virtualenv <https://pypi.python.org/pypi/virtualenv>`_.
-Now, in your terminal::
-
-  source .env/bin/activate
-  pip install git+https://github.com/tornadoweb/tornado.git
-
-In the same terminal session, start the chatroom server::
-
-  python TestChatServer/py/chatroom.py
-
-There's also a Go implementation (with the latest weekly) where you can::
-
-  cd TestChatServer/go
-  go run chatroom.go
-
-Chatting
-````````
-Now, start TestChat.app (just run the target in the Xcode project).  If you had
-it started already you can hit the refresh button to reconnect.  It should say
-"Connected!" on top.
-
-To talk with the app, open up your browser to `http://localhost:9000 <http://localhost:9000>`_ and
-start chatting.
-
-
-WebSocket Server Implementation Recommendations
------------------------------------------------
-SocketRocket has been used with the following libraries:
-
-- `Tornado <https://github.com/tornadoweb/tornado>`_
-- Go's `WebSocket package <https://godoc.org/golang.org/x/net/websocket>`_ or Gorilla's `version <http://www.gorillatoolkit.org/pkg/websocket>`_
-- `Autobahn <http://autobahn.ws/testsuite/>`_ (using its fuzzing
-  client)
-
-The Tornado one is dirt simple and works like a charm.  (`IPython notebook
-<http://ipython.org/ipython-doc/dev/interactive/htmlnotebook.html>`_ uses it
-too).  It's much easier to configure handlers and routes than in
-Autobahn/twisted.
-
-As far as Go's goes, it works in my limited testing. I much prefer go's
-concurrency model as well. Try it! You may like it.
-It could use some more control over things such as pings, etc., but I
-am sure it will come in time.
-
-Autobahn is a great test suite.  The Python server code is good, and conforms
-well (obviously).  However for me, twisted would be a deal-breaker for writing
-something new.  I find it a bit too complex and heavy for a simple service. If
-you are already using twisted though, Autobahn is probably for you.
-
-Contributing
-------------
-We’re glad you’re interested in SocketRocket, and we’d love to see where you take it. Please read our `contributing guidelines <https://github.com/facebook/SocketRocket/blob/master/Contributing.md>`_ prior to submitting a Pull Request.