Docuemntation updates

FAQ.md

@@ -602,6 +602,9 @@ Yes, sort of.  For as long as the legacy of
 Machi's first internal protocol & code still
 survives, it's possible to use a
 [primitive/hack'y HTTP interface that is described in this source code commit log](https://github.com/basho/machi/commit/6cebf397232cba8e63c5c9a0a8c02ba391b20fef).
+Please note that commit `6cebf397232cba8e63c5c9a0a8c02ba391b20fef` is
+required to try using this feature: the code has since bit-rotted and
+will not work on today's `master` branch.
 
 In the long term, we'll probably want the option of an HTTP interface
 that is as well designed and REST'ful as possible.  It's on the

README.md

@@ -37,20 +37,21 @@ being used as the initial scaffolding.
 * The chain manager is ready for "AP mode" use in eventual
   consistency use cases.
 
-* The Machi client/server protocol is still the hand-crafted,
-  artisanal, bogus protocol that I hacked together for a "demo day"
-  back in January and appears in the
-  [prototype/demo-day-hack](prototype/demo-day-hack/) code.
-    * Today: the only client language supported is Erlang.
-    * Today: an HTTP interface that, at the moment, is a big kludge.
-      If someone who really cares about an
-      HTTP interface that is 100% REST-ful cares to contribute some
-      code ... contributions are welcome!
-    * Work in progress now: replace the current protocol to something
-      based on Protocol Buffers 
-        * If you'd like to work on a protocol such as Thrift, UBF,
-          msgpack over UDP, or some other protocol, let us know by
-          [opening an issue](./issues/new) to discuss it.
+* All Machi client/server protocols are based on
+  [Protocol Buffers](https://developers.google.com/protocol-buffers/docs/overview).
+    * The current specification for Machi's protocols can be found at
+      [https://github.com/basho/machi/blob/master/src/machi.proto](https://github.com/basho/machi/blob/master/src/machi.proto).
+    * The Machi PB protocol is not yet stable.  Expect change!
+    * The Erlang language client implementation of the high-level
+      protocol flavor is very brittle (e.g., very little error
+      handling yet).
+    * The Erlang language client implementation of the low-level
+      protocol flavor are still a work-in-progress ... but they are
+      more robust than the high-level library's implementation.
+
+If you'd like to work on a protocol such as Thrift, UBF,
+msgpack over UDP, or some other protocol, let us know by
+[opening an issue](./issues/new) to discuss it.
 
 ## Contributing to Machi: source code, documentation, etc.
 

src/machi_flu1.erl

@@ -294,7 +294,7 @@ net_server_loop(Sock, S) ->
             %% TODO: Weird that sometimes neither catch nor try/catch
             %%       can prevent OTP's SASL from logging an error here.
             %%       Error in process <0.545.0> with exit value: {badarg,[{erlang,port_command,.......
-            _ = (catch gen_tcp:send(Sock, Resp)),
+            _ = (catch gen_tcp:send(Sock, Resp)), timer:sleep(1000),
             (catch gen_tcp:close(Sock)),
             exit(normal)
     end.

src/machi_flu1_client.erl

@@ -26,20 +26,7 @@
 %% management can be found in {@link machi_proxy_flu1_client} and
 %% {@link machi_cr_client}.
 %%
-%% TODO This EDoc was written first, and the EDoc and also `-type' and
-%% `-spec' definitions for {@link machi_proxy_flu1_client} and {@link
-%% machi_cr_client} must be improved.
-%%
-%% === Protocol origins ===
-%%
-%% The protocol implemented here is an artisanal, hand-crafted, silly
-%% thing that was very quick to put together for a "demo day" proof of
-%% concept.  It will almost certainly be replaced with something else,
-%% both in terms of wire format and better code separation of
-%% serialization/deserialization vs. network transport management,
-%% etc.
-%%
-%% For the moment, this module implements a rudimentary TCP-based
+%% For the moment, this module implements a Protocol Buffers-based
 %% protocol as the sole supported access method to the server,
 %% sequencer, and projection store.  Conceptually, those three
 %% services are independent and ought to have their own protocols.  As
@@ -47,6 +34,10 @@
 %% compatibility.  Furthermore, from the perspective of failure
 %% detection, it is very convenient that all three FLU-related
 %% services are accessed using the same single TCP port.
+%%
+%% TODO This EDoc was written first, and the EDoc and also `-type' and
+%% `-spec' definitions for {@link machi_proxy_flu1_client} and {@link
+%% machi_cr_client} must be improved.
 
 -module(machi_flu1_client).