Commits

Jens Alfke  committed 56a7f34

more edits

  • Participants
  • Parent commits 946cc9a

Comments (0)

Files changed (3)

File BLIP/Overview.wiki

 
 BLIP is a message-oriented network protocol that lets the two peers on either end of a TCP socket send request and response messages to each other. It's a generic protocol, in that the requests and responses can contain any kind of data you like.
 
-BLIP was inspired by [[BLIP/BEEP]] (in fact BLIP stands for "BEEP-LIke Protocol") but is deliberately simpler and somewhat more limited. That results in a smaller and cleaner implementation, especially since it takes advantage of Cocoa's and CFNetwork's existing support for network streams, SSL and Bonjour. (BLIP is currently a bit under 2,000 lines of code, and the rest of the MYNetwork classes it builds on add up to another 1,500. That's at least an order of magnitude smaller than existing native-code BEEP libraries.)
+BLIP was inspired by [[BLIP/BEEP|BEEP]] (in fact BLIP stands for "BEEP-LIke Protocol") but is deliberately simpler and somewhat more limited. That results in a smaller and cleaner implementation, especially since it takes advantage of Cocoa's and CFNetwork's existing support for network streams, SSL and Bonjour. (BLIP is currently a bit under 2,000 lines of code, and the rest of the MYNetwork classes it builds on add up to another 1,500. That's at least an order of magnitude smaller than existing native-code BEEP libraries.)
 
 BLIP is currently implemented in two forms: Objective-C for Mac OS X applications; and pure [[Python]].
 
 = Features
 
-* Each message is very much like a MIME body, as in email or HTTP: it consists of a blob of data of arbitrary length, plus a set of key/value pairs called "properties". The properties are mostly ignored by BLIP itself, but clients can use them for metadata about the body, and for delivery information (i.e. something like BEEP's "profiles".)
+* Each message is very much like a MIME body, as in email or HTTP: it consists of a blob of data of arbitrary length, plus a set of key/value pairs called "properties". The properties are mostly ignored by BLIP itself, but clients can use them for metadata about the body, and for delivery information (i.e. something like [[BLIP/BEEP|BEEP]]'s "profiles".)
 * Either peer can send a request at any time; there's no distinction between "client" and "server" roles.
 * Multiple messages can be transmitted simultaneously in the same direction over the same connection, so a very long message does not block any other messages from being delivered. This means that message ordering is a bit looser than in BEEP or HTTP 1.1: the receiver will see the beginnings of messages in the same order in which the sender posted them, but they might not end in that same order. (For example, a long message will take longer to be delivered, so it may finish after messages that were begun after it.)
 * The sender can indicate whether or not a message needs to be replied to; the response is tagged with the identity of the original message, to make it easy for the sender to recognize. This makes it straighforward to implement RPC-style (or REST-style) interactions. (Responses cannot be replied to again, however.)
 Much more detail is provided in the [[BLIP/Protocol|protocol documentation]].
 
 There is also [[http://mooseyard.com/projects/MYNetwork/annotated.html|API documentation]].
+
+{{http://groups.google.com/groups/img/3nb/groups_bar.gif}}\\
+Join the [[http://groups.google.com/group/blip-protocol|BLIP-Protocol]] Google Group!
 * A generic TCP client/server implementation, useful for implementing your own network protocols; (see TCPListener and TCPConnection)
 * An implementation of [[BLIP/Overview|BLIP]], a lightweight network protocol I've invented as an easy way to send request and response messages between peers. (see BLIPListener, BLIPConnection, BLIPRequest, etc.)
 
+== What Do the Generic Classes Do? ==
+
+For some reason the Cocoa frameworks don't include for a TCP server (also known as a listener), only for client connections. To implement a server, you have to use some low-level procedural APIs in CoreFoundation.
+
+Additionally, there are some annoying limitations of the NSStream API, particularly when writing to a stream -- NSOutputStream doesn't do any buffering, so you're in charge of spoon-feeding it data at the rate it can handle it. MYNetwork's TCPWriter takes care of that.
+
+There also turns out to be some complicated logic required for implementing time-outs when attempting to connect, and also for closing down a socket connection cleanly. TCPConnection manages that.
+
+== What's BLIP? ==
+ 
+BLIP is a message-oriented network protocol that lets the two peers on either end of a TCP socket send request and response messages to each other. It's a generic protocol, in that the requests and responses can contain any kind of data you like. 
+
 == License and Disclaimer ==
  
 MYNetwork is released under a BSD license, which means you can freely use it in open-source
 or commercial projects, provided you give credit in your documentation or About box.
- 
-As I write this (May 2008), MYNetwork is still very much under development. I am using it as the foundation of my own commercial products, at least one of which is currently at about the alpha stage. I'm making changes to this code as I see fit, fairly often.
- 
-That's good, in that the code is getting real-world use. But it also means that APIs and functionality are subject to change. (Of course, the entire revision tree is always available, so you're free to stick with any revision you like, and even "cherry-pick" desired changes from future ones.)
- 
-Not all of this code gets thoroughly exercised by my test cases or my applications, so some things may not work. Obviously, this code comes with no warranty nor any guarantee of tech support, though I will try to do my best to help out. Hopefully the source code is clear enough to let you figure out what's going on.
+
+MYNetwork has been publicly available since May 2008. So far it has been used in one shipping product that I know of -- VoodooPad 4.1, and its companion VP reader for iPhone. Its developer, Gus Mueller, calls MYNetwork “an awesome network library ... It made moving pages from VoodooPad the the iPhone over the network completely painless. A++ would recommend again.” [[http://gusmueller.com/blog/archives/2009/03/voodoopad_4.1_and_vp_reader_for_iphone_released.html|*]]
  
 If you come across bugs, please tell me about them. If you fix them, I would love to get your fixes and incorporate them. If you add features I would love to know about them, and I will incorporate them if I think they make sense for the project. Thanks!
-
-== What's BLIP? ==
- 
- <table style="background-color: #fff; padding: 5px; float: right" cellspacing=0>
- <tr><td>
- <img src="http://groups.google.com/groups/img/3nb/groups_bar.gif"
- height=26 width=132 alt="Google Groups">
- </td></tr>
- <tr><td style="padding-left: 5px;font-size: 125%">
- <b>BLIP Protocol</b>
- </td></tr>
- <tr><td style="padding-left: 5px">
- <a href="http://groups.google.com/group/blip-protocol">Visit this group</a>
- </td></tr>
- </table>
- 
-BLIP is a message-oriented network protocol that lets the two peers on either end of a TCP socket send request and response messages to each other. It's a generic protocol, in that the requests and responses can contain any kind of data you like. 
- 
-BLIP was inspired by [[BLIP/BEEP|BEEP]] (in fact BLIP stands for "BEEP-LIke Protocol") but is
-deliberately simpler and somewhat more limited. That results in a smaller and cleaner implementation, especially since it takes advantage of Cocoa's and CFNetwork's existing support for network streams, SSL and Bonjour. (BLIP is currently a bit under 2,000 lines of code, and the rest of the MYNetwork classes it builds on add up to another 1,500. That's at least an order of magnitude smaller than existing native-code BEEP libraries.)
- 
-=== BLIP Features ===
-
-* Each message is very much like a MIME body, as in email or HTTP: it consists of a
-blob of data of arbitrary length, plus a set of key/value pairs called "properties". The
-properties are mostly ignored by BLIP itself, but clients can use them for metadata about the
-body, and for delivery information (i.e. something like [[BLIP/BEEP|BEEP]]'s "profiles".)
-
-* Either peer can send a request at any time; there's no notion of "client" and "server" roles.
- 
-*  Multiple messages can be transmitted simultaneously in the same direction over the same connection, so a very long
-message does not block any other messages from being delivered. This means that message ordering
-is a bit looser than in BEEP or HTTP 1.1: the receiver will see the beginnings of messages in the
-same order in which the sender posted them, but they might not <i>end</i> in that same order. (For
-example, a long message will take longer to be delivered, so it may finish after messages that
-were begun after it.)
-
-* The sender can indicate whether or not a message needs to be replied to; the response is tagged with the
-identity of the original message, to make it easy for the sender to recognize. This makes it
-straighforward to implement RPC-style (or REST-style) interactions. (Responses
-cannot be replied to again, however.)
-
-* A message can be flagged as "urgent". Urgent messages are pushed ahead in the outgoing queue and
-get a higher fraction of the available bandwidth.
-
-* A message can be flagged as "compressed". This runs its body through the gzip algorithm, ideally
-making it faster to transmit. (Common markup-based data formats like XML and JSON compress
-extremely well, at ratios up to 10::1.) The message is decompressed on the receiving end,
-invisibly to client code.
- 
-* The implementation supports SSL connections (with optional client-side certificates), and Bonjour service advertising.
 == Using the Python BLIP Implementation ==
 
-The Python implementation of BLIP consists of the file {{{BLIP.py}}} //(only 500 lines!)// in the "{{{Python/}}}" subdirectory of the MYNetwork repository.
+The Python implementation of [[BLIP/Overview|BLIP]] consists of the file {{{BLIP.py}}} //(only 500 lines!)// in the "{{{Python/}}}" subdirectory of the MYNetwork repository.
 
 To run the test cases, execute this in a shell:
 {{{