diff --git a/.bookignore b/.bookignore new file mode 100644 index 0000000..e272259 --- /dev/null +++ b/.bookignore @@ -0,0 +1,9 @@ + +_book/ +_examples/ +tools/ + +Makefile +building_the_book.md +.gitignore +.bookignore \ No newline at end of file diff --git a/.gitignore b/.gitignore index c585121..8584717 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ _book/ .vscode -node_modules \ No newline at end of file +.idea/ +node_modules diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5a9417c --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +build: init examples + gitbook build . docs + +init: + gitbook install + +serve: + gitbook serve + +examples: + go run tools/examplecompiler/main.go -o _examples -r tools/examplecompiler/example_repos.json -t tools/examplecompiler/example_template.tmp diff --git a/developer/examples/connect_default.html b/_examples/connect_default.html similarity index 100% rename from developer/examples/connect_default.html rename to _examples/connect_default.html diff --git a/developer/examples/connect_multiple.html b/_examples/connect_multiple.html similarity index 100% rename from developer/examples/connect_multiple.html rename to _examples/connect_multiple.html diff --git a/developer/examples/connect_name.html b/_examples/connect_name.html similarity index 100% rename from developer/examples/connect_name.html rename to _examples/connect_name.html diff --git a/developer/examples/connect_options.html b/_examples/connect_options.html similarity index 100% rename from developer/examples/connect_options.html rename to _examples/connect_options.html diff --git a/developer/examples/connect_pedantic.html b/_examples/connect_pedantic.html similarity index 100% rename from developer/examples/connect_pedantic.html rename to _examples/connect_pedantic.html diff --git a/developer/examples/connect_status.html b/_examples/connect_status.html similarity index 100% rename from developer/examples/connect_status.html rename to _examples/connect_status.html diff --git a/developer/examples/connect_tls.html b/_examples/connect_tls.html similarity index 100% rename from developer/examples/connect_tls.html rename to _examples/connect_tls.html diff --git a/developer/examples/connect_tls_url.html b/_examples/connect_tls_url.html similarity index 100% rename from developer/examples/connect_tls_url.html rename to _examples/connect_tls_url.html diff --git a/developer/examples/connect_token.html b/_examples/connect_token.html similarity index 100% rename from developer/examples/connect_token.html rename to _examples/connect_token.html diff --git a/developer/examples/connect_token_url.html b/_examples/connect_token_url.html similarity index 100% rename from developer/examples/connect_token_url.html rename to _examples/connect_token_url.html diff --git a/developer/examples/connect_url.html b/_examples/connect_url.html similarity index 100% rename from developer/examples/connect_url.html rename to _examples/connect_url.html diff --git a/developer/examples/connect_userpass.html b/_examples/connect_userpass.html similarity index 100% rename from developer/examples/connect_userpass.html rename to _examples/connect_userpass.html diff --git a/developer/examples/connect_userpass_url.html b/_examples/connect_userpass_url.html similarity index 100% rename from developer/examples/connect_userpass_url.html rename to _examples/connect_userpass_url.html diff --git a/developer/examples/connect_verbose.html b/_examples/connect_verbose.html similarity index 100% rename from developer/examples/connect_verbose.html rename to _examples/connect_verbose.html diff --git a/developer/examples/connection_listener.html b/_examples/connection_listener.html similarity index 100% rename from developer/examples/connection_listener.html rename to _examples/connection_listener.html diff --git a/developer/examples/control_2k.html b/_examples/control_2k.html similarity index 100% rename from developer/examples/control_2k.html rename to _examples/control_2k.html diff --git a/developer/examples/drain_conn.html b/_examples/drain_conn.html similarity index 100% rename from developer/examples/drain_conn.html rename to _examples/drain_conn.html diff --git a/developer/examples/drain_sub.html b/_examples/drain_sub.html similarity index 100% rename from developer/examples/drain_sub.html rename to _examples/drain_sub.html diff --git a/developer/examples/error_listener.html b/_examples/error_listener.html similarity index 100% rename from developer/examples/error_listener.html rename to _examples/error_listener.html diff --git a/developer/examples/flush.html b/_examples/flush.html similarity index 100% rename from developer/examples/flush.html rename to _examples/flush.html diff --git a/developer/examples/max_payload.html b/_examples/max_payload.html similarity index 100% rename from developer/examples/max_payload.html rename to _examples/max_payload.html diff --git a/developer/examples/no_echo.html b/_examples/no_echo.html similarity index 100% rename from developer/examples/no_echo.html rename to _examples/no_echo.html diff --git a/developer/examples/ping_20s.html b/_examples/ping_20s.html similarity index 100% rename from developer/examples/ping_20s.html rename to _examples/ping_20s.html diff --git a/developer/examples/ping_5.html b/_examples/ping_5.html similarity index 100% rename from developer/examples/ping_5.html rename to _examples/ping_5.html diff --git a/developer/examples/publish_bytes.html b/_examples/publish_bytes.html similarity index 100% rename from developer/examples/publish_bytes.html rename to _examples/publish_bytes.html diff --git a/developer/examples/publish_json.html b/_examples/publish_json.html similarity index 100% rename from developer/examples/publish_json.html rename to _examples/publish_json.html diff --git a/developer/examples/publish_with_reply.html b/_examples/publish_with_reply.html similarity index 100% rename from developer/examples/publish_with_reply.html rename to _examples/publish_with_reply.html diff --git a/developer/examples/reconnect_10s.html b/_examples/reconnect_10s.html similarity index 100% rename from developer/examples/reconnect_10s.html rename to _examples/reconnect_10s.html diff --git a/developer/examples/reconnect_10x.html b/_examples/reconnect_10x.html similarity index 100% rename from developer/examples/reconnect_10x.html rename to _examples/reconnect_10x.html diff --git a/developer/examples/reconnect_5mb.html b/_examples/reconnect_5mb.html similarity index 100% rename from developer/examples/reconnect_5mb.html rename to _examples/reconnect_5mb.html diff --git a/developer/examples/reconnect_event.html b/_examples/reconnect_event.html similarity index 100% rename from developer/examples/reconnect_event.html rename to _examples/reconnect_event.html diff --git a/developer/examples/reconnect_no_random.html b/_examples/reconnect_no_random.html similarity index 100% rename from developer/examples/reconnect_no_random.html rename to _examples/reconnect_no_random.html diff --git a/developer/examples/reconnect_none.html b/_examples/reconnect_none.html similarity index 100% rename from developer/examples/reconnect_none.html rename to _examples/reconnect_none.html diff --git a/developer/examples/request_reply.html b/_examples/request_reply.html similarity index 100% rename from developer/examples/request_reply.html rename to _examples/request_reply.html diff --git a/developer/examples/servers_added.html b/_examples/servers_added.html similarity index 100% rename from developer/examples/servers_added.html rename to _examples/servers_added.html diff --git a/developer/examples/slow_listener.html b/_examples/slow_listener.html similarity index 100% rename from developer/examples/slow_listener.html rename to _examples/slow_listener.html diff --git a/developer/examples/slow_pending_limits.html b/_examples/slow_pending_limits.html similarity index 100% rename from developer/examples/slow_pending_limits.html rename to _examples/slow_pending_limits.html diff --git a/developer/examples/subscribe_arrow.html b/_examples/subscribe_arrow.html similarity index 100% rename from developer/examples/subscribe_arrow.html rename to _examples/subscribe_arrow.html diff --git a/developer/examples/subscribe_async.html b/_examples/subscribe_async.html similarity index 100% rename from developer/examples/subscribe_async.html rename to _examples/subscribe_async.html diff --git a/developer/examples/subscribe_json.html b/_examples/subscribe_json.html similarity index 100% rename from developer/examples/subscribe_json.html rename to _examples/subscribe_json.html diff --git a/developer/examples/subscribe_queue.html b/_examples/subscribe_queue.html similarity index 100% rename from developer/examples/subscribe_queue.html rename to _examples/subscribe_queue.html diff --git a/developer/examples/subscribe_star.html b/_examples/subscribe_star.html similarity index 100% rename from developer/examples/subscribe_star.html rename to _examples/subscribe_star.html diff --git a/developer/examples/subscribe_sync.html b/_examples/subscribe_sync.html similarity index 100% rename from developer/examples/subscribe_sync.html rename to _examples/subscribe_sync.html diff --git a/developer/examples/subscribe_w_reply.html b/_examples/subscribe_w_reply.html similarity index 100% rename from developer/examples/subscribe_w_reply.html rename to _examples/subscribe_w_reply.html diff --git a/developer/examples/unsubscribe.html b/_examples/unsubscribe.html similarity index 100% rename from developer/examples/unsubscribe.html rename to _examples/unsubscribe.html diff --git a/developer/examples/unsubscribe_auto.html b/_examples/unsubscribe_auto.html similarity index 100% rename from developer/examples/unsubscribe_auto.html rename to _examples/unsubscribe_auto.html diff --git a/developer/examples/wildcard_tester.html b/_examples/wildcard_tester.html similarity index 100% rename from developer/examples/wildcard_tester.html rename to _examples/wildcard_tester.html diff --git a/book.json b/book.json index d0a212c..a8f1634 100644 --- a/book.json +++ b/book.json @@ -1,4 +1,7 @@ { + "title" : "NATS", + "description": "Administrative, developer and conceptual documentation for the NATS messaging system.", + "author": "The NATS Maintainers", "plugins" : [ "prism", "-highlight", "include-html"], "pluginsConfig": { diff --git a/developer/connecting.md b/developer/connecting.md index 3350120..96a07fd 100644 --- a/developer/connecting.md +++ b/developer/connecting.md @@ -1,24 +1,24 @@ # Connecting to NATS -Most client libraries provide several ways to connect to the NATS server, gnatsd. 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. +Most client libraries provide several ways to connect to the NATS server, gnatsd. 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. ## Connecting to a Specific Server For example, to connect to the demo server with a URL: -!INCLUDE "examples/connect_url.html" +!INCLUDE "../_examples/connect_url.html" ## 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" +!INCLUDE "../_examples/connect_default.html" ## 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" +!INCLUDE "../_examples/connect_options.html" The available options are discussed more below, in other pages, and in the documentation for your client library. @@ -33,7 +33,7 @@ When connecting to a cluster, there are a few things to think about. 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" +!INCLUDE "../_examples/connect_multiple.html" ## Reconnecting @@ -43,37 +43,37 @@ Most, if not all, of the client libraries will reconnect to the server if they a For example, you can disable reconnect: -!INCLUDE "examples/reconnect_none.html" +!INCLUDE "../_examples/reconnect_none.html" ### Set the Number of Reconnect Attempts Applications can set the maximum reconnect attempts. Generally, this will limit the actual number of attempts total, but check your library documentation. For example, in Java, if the client knows about 3 servers and the maximum reconnects is set to 2, it will not try all of the servers. On the other hand, if the maximum is set to 6 it will try all of the servers twice before considering the reconnect a failure and closing. -!INCLUDE "examples/reconnect_10x.html" +!INCLUDE "../_examples/reconnect_10x.html" ### Pausing Between Reconnect Attempts It doesn’t make much sense to try to connect to the same server over and over. To prevent this sort of thrashing, and wasted reconnect attempts, libraries provide a wait setting. This setting will pause the reconnect logic if the same server is being tried multiple times. In the previous example, if you have 3 servers and 6 attempts, the Java library would loop over the three servers. If none were connectable, it will then try all three again. However, the Java client doesn’t wait between each attempt, only when trying the same server again, so in that example the library may never wait. If on the other hand, you only provide a single server URL and 6 attempts, the library will wait between each attempt. -!INCLUDE "examples/reconnect_10s.html" +!INCLUDE "../_examples/reconnect_10s.html" ### Avoiding the Thundering Herd When a server goes down, there is a possible anti-pattern called the *Thundering Herd* where all of the clients try to reconnect immediately creating a denial of service attack. In order to prevent this, most NATS client libraries randomize the servers they attempt to connect to. This setting has no effect if only a single server is used, but in the case of a cluster, randomization, or shuffling, will ensure that no one server bears the brunt of the client reconnect attempts. -!INCLUDE "examples/reconnect_no_random.html" +!INCLUDE "../_examples/reconnect_no_random.html" ### Listening for Reconnect Events Because reconnect is primarily under the covers many libraries provide an event listener you can use to be notified of reconnect events. This event can be especially important for applications sending a lot of messages. -!INCLUDE "examples/reconnect_event.html" +!INCLUDE "../_examples/reconnect_event.html" ### Buffering Messages During Reconnect Attempts There is another setting that comes in to play during reconnection. This setting controls how much memory the client library will hold in the form of outgoing messages while it is disconnected. During a short reconnect, the client will generally allow applications to publish messages but because the server is offline, will be cached in the client. The library will then send those messages on reconnect. When the maximum reconnect buffer is reached, messages will no longer be publishable by the client. -!INCLUDE "examples/reconnect_5mb.html" +!INCLUDE "../_examples/reconnect_5mb.html" > *As mentioned throughout this document, each client library may behave slightly differently. Please check the documentation for the library you are using.* \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index c585121..0000000 --- a/docs/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -_book/ - -.vscode -node_modules \ No newline at end of file diff --git a/docs/developer/connecting.html b/docs/developer/connecting.html index e3d7528..ad334de 100644 --- a/docs/developer/connecting.html +++ b/docs/developer/connecting.html @@ -4,11 +4,11 @@ - Connecting · GitBook + Connecting · NATS - + @@ -102,10 +102,9 @@ -