Moved tools to _tools

Broke up develoepr doc into tree
Small CSS tweak to give diagrams more room

developer/connecting/cluster.md

@@ -0,0 +1,12 @@
+# Connecting to a Cluster
+
+When connecting to a cluster, there are a few things to think about.
+
+* Passing a URL for each cluster member (semi-optional)
+* The connection algorithm
+* The reconnect algorithm (discussed later)
+* Server provided URLs
+
+When a client connects to the server, the server may provide a list of URLs for additional known servers. This allows a client to connect to one server and still have other servers available during reconnect. However, the initial connection cannot depend on these additional servers. Rather, the additional connection will try to connect to each of the URLs provided in the connect call and will fail if it is unable to connect to any of them. *Note, failure behavior is library dependent, please check the documentation for your client library on information about what happens if the connect fails.*
+
+!INCLUDE "../../_examples/connect_multiple.html"

developer/connecting/connect_timeout.md

@@ -0,0 +1,5 @@
+# Setting a Connect Timeout
+
+Each library has its own, language preferred way, to pass connection options. For example, to set the maximum time to connect to a server to 10 seconds:
+
+!INCLUDE "../../_examples/connect_options.html"

developer/connecting/default_server.md

@@ -0,0 +1,5 @@
+# Connecting to the Default Server
+
+Some libraries also provide a special way to connect to a *default* url, which is general `nats://localhost:4222`:
+
+!INCLUDE "../../_examples/connect_default.html"

developer/connecting/intro.md

@@ -0,0 +1,5 @@
+# Connecting to NATS
+
+Most client libraries provide several ways to connect to the NATS server, gnatsd recently updated to nats-server. The server itself is identified by a standard URL with the `nats` protocol. Throughout these examples we will rely on a test server, provided by [nats.io](https://nats.io), at `nats://demo.nats.io:4222`, where `4222` is the default port for NATS.
+
+There are numerous options for a NATS connections.

developer/connecting/name.md

@@ -0,0 +1,5 @@
+# Setting the Connection Name
+
+Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required but can help in debugging and testing.
+
+!INCLUDE "../../_examples/connect_name.html"

developer/connecting/noecho.md

@@ -0,0 +1,34 @@
+# Turning Off Echo'd Messages
+
+By default the server will echo messages. This means that if a publisher on a connection sends a message to a subject any subscribers on that same connection may receive the message. Turning off echo is a fairly new feature for the NATS server, but some of the clients already support it.
+
+<div class="graphviz"><code data-viz="dot">
+digraph {
+  rankdir=LR;
+  subgraph cluster_1 {
+        shape=box;
+        style="rounded";
+        label = "Connection #1";
+
+        publisher [shape=box, style="rounded", label="Publisher"];
+        subscriber_1 [shape=box, style="rounded", label="Subscriber"];
+    }
+  subgraph cluster_2 {
+        shape=box;
+        style="rounded";
+        label = "Connection #2";
+
+        subscriber_2 [shape=box, style="rounded", label="Subscriber"];
+    }
+
+    subject [shape=circle, label="Subject"];
+
+    publisher -> subject [label="msg"];
+    subject -> subscriber_1 [label="echo'd msg", style="dashed"];
+    subject -> subscriber_2 [label="msg"];
+}
+</code></div>
+
+Keep in mind that each connection will have to turn off echo, and that it is per connection, not per application. Also, turning echo on and off can result in a major change to your applications communications protocol since messages will flow or stop flowing based on this setting and the subscribing code won't have any indication as to why.
+
+!INCLUDE "../../_examples/no_echo.html"

developer/connecting/pingpong.md

@@ -0,0 +1,28 @@
+# Ping/Pong Protocol
+
+The client and server use a simple PING/PONG protocol to check that they are both still connected. The client will ping the server on a regular, configured interval so that the server usually doesn't have to initiate the PING/PONG interaction.
+
+<div class="graphviz"><code data-viz="dot">
+digraph g {
+  rankdir=LR
+  client [shape=box, style="rounded", label="NATS Client"];
+  gnatsd [shape=circle, label="gnatsd"];
+
+  client -> gnatsd [label="PING"];
+  gnatsd -> client [label="PONG"];
+}
+</code></div>
+
+## Set the Ping Interval
+
+If you have a connection that is going to be open a long time with few messages traveling on it, setting this PING interval can control how quickly the client will be notified of a problem. However on connections with a lot of traffic, the client will often figure out there is a problem between PINGS, and as a result the default PING interval is often on the order of minutes. To set the interval to 20s:
+
+!INCLUDE "../../_examples/ping_20s.html"
+
+## Limit Outgoing Pings
+
+The PING/PONG interaction is also used by most of the clients as a way to flush the connection to the server. Clients that cache outgoing messages provide a flush call that will run a PING/PONG. The flush will wait for the PONG to return, telling it that all cached messages have been processed, including the PING. The number of cached PING requests can be limited in most clients to insure that traffic problems are identified early. This configuration for _max outgoing pings_ or similar will usually default to a small number and should only be increased if you are worried about fast flush traffic, perhaps in multiple threads.
+
+For example, to set the maximum number of outgoing pings to 5:
+
+!INCLUDE "../../_examples/ping_5.html"

developer/connecting/protocol.md

@@ -0,0 +1,29 @@
+# Controlling the Client/Server Protocol
+
+The protocol between the client and the server is fairly simple and relies on a control line and sometimes a body. The control line contains the operations being sent, like PING or PONG, followed by a carriage return and line feed, CRLF or "\r\n". The server has a setting that can limit the maximum size of a control line. For PING and PONG this doesn't come into play, but for messages that contain subject names, the control line length can be important. The server is also configured with a maximum payload size, which limits the size of a message body. The server sends the maximum payload size to the client at connect time but doesn't currently tell the client the maximum control line size.
+
+## Set the Maximum Control Line Size
+
+Some clients will try to limit the control line size on themselves to prevent an error from the server. These clients may or may not allow you to set the size being used, but if they do, the size should be set to match the server configuration.
+
+For example, to set the maximum control line size to 2k:
+
+!INCLUDE "../../_examples/control_2k.html"
+
+## Get the Maximum Payload Size
+
+While the client can't control the maximum payload size, clients may provide a way for applications to get the size after the connection is made. This will allow the application to chunk or limit data as needed to pass through the server.
+
+!INCLUDE "../../_examples/max_payload.html"
+
+## Turn On Pedantic Mode
+
+The NATS server provides a _pedantic_ mode that does extra checks on the protocol. By default, this setting is off but you can turn it on:
+
+!INCLUDE "../../_examples/connect_pedantic.html"
+
+## Turn On/Off Verbose Mode
+
+The NATS server also provide a _verbose_ mode. By default, verbose mode is enabled and the server will reply to every message from the client with either a +OK or a -ERR. Most clients turn off verbose mode, which disables all of the +OK traffic. Errors are rarely subject to verbose mode and client libraries handle them as documented. To turn on verbose mode, likely for testing:
+
+!INCLUDE "../../_examples/connect_verbose.html"

developer/connecting/specific_server.md

@@ -0,0 +1,5 @@
+# Connecting to a Specific Server
+
+For example, to connect to the demo server with a URL:
+
+!INCLUDE "../../_examples/connect_url.html"