Tutorials (#369)

* tutorial setup test * colorizing tutorial * colorizing * theme change for code * layout * added tutorial section * fixed back links * Added some samples from the tutorialcompiler, added support for copy/paste * menu placeholder * styles troubleshoot * Renamed to NewDoc, fixed style issue, checked in partialsfor example. * Initial doc page with copied content for non-api stuff. Connection example page, and placeholders for others. * Added classes and data to enable consistent language choices across all tabs. Store the choice in session storage so it spans pages. * updated fonts * updated icon names * Fixed issue with JS remembering lang but only for tabs. * fixed toolbar icon spacing fixed tooltip location * removed text decoration from links in a toolbar-icon * tweak spacing of icons * updated with toolbar-icons class * Moved diagrams in concepts to graphviz. Added connection options writeup, with Java examples. Added graphviz support in js * Added secure_connection.md and partials with examples for java. * Moved concepts into Writing apps section and combined into 1 page. Created pages for publishing and advanced topics like events. Commited examples from Java for all writing apps sections. * Small rework of server examples, added some TypeScript * Added more go examples from ivan * Added lots of go examples! * Reviewed and updated internals doc. Included a couple new go examples. * Reviewed streaming section for new doc * Switched bash to sh in code sections. Reviewed, cleaned up tutorials * renamed writing apps to writing applications added some markers in cncepts reviewed, updated contributing, index and faq created getting started section * Removed old documentation folder/menu * Removed old documentation partials * Changed the way graphviz is included to be less flashy. * Moved writing apps to writing applications, should have done this sooner, links were alreayd updated. * Updated writing applications section based on ginger's comments. * Added asyncio and typescript examples. * Updated TS examples. * Added drain examples and description. * Updated examples, in particular the go examples with not applicable comments. * Proof reading updates * Added custom dialer writup from wally and updated examples code. * Added ruby examples * Added node examples! * Updated examples with more N/A descriptions from JS and TS * Updated some ts examples * updated prism versions, added ruby. * Moved connection drain above sub drain Added query string for lang so you can link to it * Updated go examples with short URL * Change to header style weight to fix optical issue with H3 > H2 * colorizing tutorial * colorizing * theme change for code * layout * added tutorial section * fixed back links * Added some samples from the tutorialcompiler, added support for copy/paste * menu placeholder * styles troubleshoot * Renamed to NewDoc, fixed style issue, checked in partialsfor example. * Initial doc page with copied content for non-api stuff. Connection example page, and placeholders for others. * Added classes and data to enable consistent language choices across all tabs. Store the choice in session storage so it spans pages. * updated fonts * updated icon names * Fixed issue with JS remembering lang but only for tabs. * fixed toolbar icon spacing fixed tooltip location * removed text decoration from links in a toolbar-icon * tweak spacing of icons * updated with toolbar-icons class * Moved diagrams in concepts to graphviz. Added connection options writeup, with Java examples. Added graphviz support in js * Added secure_connection.md and partials with examples for java. * Moved concepts into Writing apps section and combined into 1 page. Created pages for publishing and advanced topics like events. Commited examples from Java for all writing apps sections. * Small rework of server examples, added some TypeScript * Added more go examples from ivan * Added lots of go examples! * Reviewed and updated internals doc. Included a couple new go examples. * Reviewed streaming section for new doc * Switched bash to sh in code sections. Reviewed, cleaned up tutorials * renamed writing apps to writing applications added some markers in cncepts reviewed, updated contributing, index and faq created getting started section * Removed old documentation folder/menu * Removed old documentation partials * Changed the way graphviz is included to be less flashy. * Moved writing apps to writing applications, should have done this sooner, links were alreayd updated. * Updated writing applications section based on ginger's comments. * Added asyncio and typescript examples. * Updated TS examples. * Added drain examples and description. * Updated examples, in particular the go examples with not applicable comments. * Proof reading updates * Added custom dialer writup from wally and updated examples code. * Added ruby examples * Added node examples! * Updated examples with more N/A descriptions from JS and TS * Updated some ts examples * updated prism versions, added ruby. * Moved connection drain above sub drain Added query string for lang so you can link to it * Updated go examples with short URL * Change to header style weight to fix optical issue with H3 > H2 * Updated nats queueing based on PR * Removed extra file from rebase
nats-io · Sep 6, 2018 · 8d27173 · 8d27173
1 parent c516f78
commit 8d27173
Show file tree

Hide file tree

Showing 135 changed files with 10,501 additions and 2,454 deletions.
diff --git a/README.md b/README.md
@@ -299,7 +299,7 @@ If you are running on MacOS, you can try issuing the command `make setup`, this
 
 Enter the following commands to install additional software dependencies (if you used `make setup` you can skip this next step.)
 
-```bash
+```sh
 npm install
 npm install --global gulp-cli
 ```
@@ -308,14 +308,14 @@ npm install --global gulp-cli
 
 Images and other source assets live in the `src` directory. The build workflow will resize images, and compile files in `src` and create the assets directory for hugo.
 
-```bash
+```sh
 gulp build
 ```
 
 The `gulp` command will do a build of the src directory and copy assets to the the `static` directory. This command will also run hugo and process the `content` directory creating a snapshot of the site in the `public` directory.
 
 To preview your changes, run:
-```bash
+```sh
 hugo server
 ```
 
@@ -327,7 +327,7 @@ Whenever `src` is modified, remember to run `gulp build` to update the `static`
 
 
 Create a new blog post : 
-```bash
+```sh
 hugo new blog/my-blog-post.md
 ```
 
diff --git a/config.toml b/config.toml
@@ -79,38 +79,38 @@ parent = "nats-streaming"
 [[menu.main]]
 name = "Documentation"
 weight = 3
-identifier = "documentation"
-url = "/documentation"
+identifier = "doc"
+url = "/doc"
 
 [[menu.main]]
-name = "Getting Started"
+name = "Getting Started With NATS"
 weight = 1
-parent = "documentation"
+parent = "doc"
 
 [[menu.main]]
-name = "Concepts"
+name = "Writing Applications"
 weight = 2
-parent = "documentation"
+parent = "doc"
 
 [[menu.main]]
-name = "Internals"
+name = "Managing the Server"
 weight = 3
-parent = "documentation"
+parent = "doc"
 
 [[menu.main]]
-name = "Server"
+name = "NATS Internals"
 weight = 4
-parent = "documentation"
+parent = "doc"
 
 [[menu.main]]
-name = "Streaming"
+name = "Event Streaming"
 weight = 5
-parent = "documentation"
+parent = "doc"
 
 [[menu.main]]
-name = "Tutorials"
+name = "Additional Documentation"
 weight = 6
-parent = "documentation"
+parent = "doc"
 
 [[menu.main]]
 name = "Support"

diff --git a/content/documentation/_index.md → content/doc/_index.md b/content/documentation/_index.md → content/doc/_index.md
@@ -1,28 +1,26 @@
 +++
 title = "NATS Documentation"
 category = "documentation"
-showChildren=true
 [menu.main]
-  name = "Intro"
-  weight = -100
-  identifier = "intro"
-  parent = "Getting Started"
+  name = "Introduction"
+  weight = 1
+  identifier = "doc-intro"
+  parent = "Getting Started With NATS"
 +++
 
-
 # NATS Introduction
 
 [NATS](http://nats.io/) is an open-source, cloud-native messaging system. Companies like Apcera, Baidu, Siemens, VMware, HTC, and Ericsson rely on NATS for its highly performant and resilient messaging capabilities.
 
 ## NATS server
 
-NATS provides a lightweight [server](/documentation/server/gnatsd-intro/) that is written in the Go programming language. NATS is maintained by Synadia and an amazing OpenSource Ecosystem, find more at [GitHub](http://www.github.com/nats-io).
+NATS provides a lightweight [server](/doc/managing_the_server/installing/) that is written in the Go programming language. NATS is maintained by Synadia and an amazing OpenSource Ecosystem, find more at [GitHub](http://www.github.com/nats-io).
 
 ## NATS clients
 
 There are several [client libraries](/download/) for NATS. Synadia actively maintains and supports the Go, Node, Ruby, Java, C, C# and NGINX C clients, and there are several community-provided clients.
 
-You can write your own client in any language you choose. NATS provides a simple, [text-based protocol](/documentation/internals/nats-protocol/) that makes [writing clients](/documentation/internals/nats-guide) a breeze.
+You can write your own client in any language you choose. NATS provides a simple, [text-based protocol](/doc/internals/nats-protocol/) that makes [writing clients](/doc/writing_applications/concepts) a breeze.
 
 ## <a name="design-goals"></a>NATS design goals
 
@@ -31,7 +29,7 @@ The core principles underlying NATS are performance, scalability, and ease-of-us
 - Highly performant (fast)
 - Always on and available (dial tone)
 - Extremely lightweight (small footprint)
-- Support for multiple qualities of service (including guaranteed "at-least-once" delivery with [NATS Streaming](/documentation/streaming/nats-streaming-intro/))
+- Support for multiple qualities of service (including guaranteed "at-least-once" delivery with [NATS Streaming](/doc/streaming/nats-streaming-intro/))
 - Support for various messaging models and use cases (flexible)
 
 ## NATS use cases
@@ -48,7 +46,7 @@ Some of the use cases and requirements that are ideal for NATS include:
 - **Location transparency** - your applications need to scale to a very high number of instances spread out geographically, and you can't afford the fragility of tightly coupling your applications with detailed, specific endpoint-configuration information about where other applications are, and what type of data they are producing or consuming. 
 - **Fault tolerance** - your application needs to be highly resilient to network or other outages that may be beyond your control, and you need the underlying application data communication to seamlessly recover from connectivity outages 
 
-With [NATS Streaming](/documentation/streaming/nats-streaming-intro/), a data streaming service for NATS, additional use cases include:
+With [NATS Streaming](/doc/streaming/nats-streaming-intro/), a data streaming service for NATS, additional use cases include:
 
 - Event streaming with replay from specific time or sequence (or relevant offset)
 - Durable subscriptions for transient clients  
@@ -58,40 +56,40 @@ With [NATS Streaming](/documentation/streaming/nats-streaming-intro/), a data st
 
 NATS supports various messaging models, including:
 
-- [Publish Subscribe](/documentation/concepts/nats-pub-sub/)
-- [Request Reply](/documentation/concepts/nats-req-rep/)
-- [Queueing](/documentation/concepts/nats-queueing/)
+- [Publish Subscribe](/doc/writing_applications/concepts#pubsub)
+- [Request Reply](/doc/writing_applications/concepts#reqrep)
+- [Queueing](/doc/writing_applications/concepts#queue)
 
 ## NATS features
 
 NATS provides the following unique features:
 
-- [Pure pub-sub](/documentation/server/gnatsd-intro/)
+- [Pure pub-sub](/doc/managing_the_server/running)
 	- Never assumes the audience.
 	- Always "on" dial tone.
-- [Clustered mode server](/documentation/server/gnatsd-cluster/)
+- [Clustered mode server](/doc/managing_the_server/clustering)
 	- NATS servers can be clustered together.
 	- Distributed queueing across clusters.
 	- Cluster-aware clients.
-- [Auto-pruning of subscribers](/documentation/server/gnatsd-prune/)
+- [Auto-pruning of subscribers](/doc/managing_the_server/slow_consumers)
 	- To support scaling, NATS provides for auto-pruning of client connections.
 	- If a client app is slow consuming messages, NATS will cut off the client.
 	- If a client is not responsive within the ping-pong interval, the server cuts it off.
 	- Clients implement retry logic.
-- [Text-based protocol](/documentation/internals/nats-protocol/)
+- [Text-based protocol](/doc/internals/nats-protocol)
 	- Makes it easy to get started with new clients.
 	- Does not affect server performance.
 	- Can [Telnet](https://en.wikipedia.org/wiki/Telnet) directly to the server and send messages across the wire.
 - Multiple qualities of service (QoS)
     - At-most-once delivery (TCP level reliability) - NATS delivers messages to immediately eligible subscribers but does not persist the messages.
-    - At-least-once delivery (via [NATS Streaming](/documentation/streaming/nats-streaming-intro/)) - Messages persisted until delivery to subscribers has been confirmed, or timeout expires, or storage exhausted.
-- Durable subscriptions (via [NATS Streaming](/documentation/streaming/nats-streaming-intro/))
+    - At-least-once delivery (via [NATS Streaming](/doc/streaming/nats-streaming-intro)) - Messages persisted until delivery to subscribers has been confirmed, or timeout expires, or storage exhausted.
+- Durable subscriptions (via [NATS Streaming](/doc/streaming/nats-streaming-intro))
     - Subscription delivery state is maintained so that durable subscriptions may pick up where they left off during a previous session.
-- Event streaming service (via [NATS Streaming](/documentation/streaming/nats-streaming-intro/))
+- Event streaming service (via [NATS Streaming](/doc/streaming/nats-streaming-intro))
     - Messages may be persisted to memory, file, or other secondary storage for later replay by time, sequence number, or relative offset.
-- Last/Initial value caching (via [NATS Streaming](/documentation/streaming/nats-streaming-intro/))
+- Last/Initial value caching (via [NATS Streaming](/doc/streaming/nats-streaming-intro))
     - Subscription delivery can begin with the most recently published message for a subscription.
 
 ## NATS FAQs
 
-See our [FAQ page](/documentation/faq).
+See our [FAQ page](/doc/faq).
diff --git a/content/doc/additional_documentation/custom_dialer.md b/content/doc/additional_documentation/custom_dialer.md
@@ -0,0 +1,141 @@
++++
+title = "Advanced Connect and Custom Dialer"
+description = ""
+category = "tutorials"
+[menu.main]
+  name = "Custom Dialers"
+  weight = 3
+  identifier = "doc-custom-dialer"
+  parent = "Additional Documentation"
++++
+
+The Go NATS client features a [CustomDialer](https://godoc.org/github.com/nats-io/go-nats#CustomDialer) option which allows you to customize
+the connection logic against the NATS server without having to modify the internals
+of the client. For example, let's say that you want to make the client use the `context`
+package to use `DialContext` and be able to cancel connecting to NATS altogether with a deadline,
+you could then do define a Dialer implementation as follows:
+
+```go
+package main
+
+import (
+	"context"
+	"log"
+	"net"
+	"time"
+
+	"github.com/nats-io/go-nats"
+)
+
+type customDialer struct {
+	ctx             context.Context
+	nc              *nats.Conn
+	connectTimeout  time.Duration
+	connectTimeWait time.Duration
+}
+
+func (cd *customDialer) Dial(network, address string) (net.Conn, error) {
+	ctx, cancel := context.WithTimeout(cd.ctx, cd.connectTimeout)
+	defer cancel()
+
+	for {
+		log.Println("Attempting to connect to", address)
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+
+		select {
+		case <-cd.ctx.Done():
+			return nil, cd.ctx.Err()
+		default:
+			d := &net.Dialer{}
+			if conn, err := d.DialContext(ctx, network, address); err == nil {
+				log.Println("Connected to NATS successfully")
+				return conn, nil
+			} else {
+				time.Sleep(cd.connectTimeWait)
+			}
+		}
+	}
+}
+```
+
+With the dialer implementation above, the NATS client will retry a number of times to connect
+to the NATS server until the context is no longer valid:
+
+```go
+func main() {
+	// Parent context cancels connecting/reconnecting altogether.
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var err error
+	var nc *nats.Conn
+	cd := &customDialer{
+		ctx:             ctx,
+		connectTimeout:  10 * time.Second,
+		connectTimeWait: 1 * time.Second,
+	}
+	opts := []nats.Option{
+		nats.SetCustomDialer(cd),
+		nats.ReconnectWait(2 * time.Second),
+		nats.ReconnectHandler(func(c *nats.Conn) {
+			log.Println("Reconnected to", c.ConnectedUrl())
+		}),
+		nats.DisconnectHandler(func(c *nats.Conn) {
+			log.Println("Disconnected from NATS")
+		}),
+		nats.ClosedHandler(func(c *nats.Conn) {
+			log.Println("NATS connection is closed.")
+		}),
+		nats.NoReconnect(),
+	}
+	go func() {
+		nc, err = nats.Connect("127.0.0.1:4222", opts...)
+	}()
+
+WaitForEstablishedConnection:
+	for {
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// Wait for context to be canceled either by timeout
+		// or because of establishing a connection...
+		select {
+		case <-ctx.Done():
+			break WaitForEstablishedConnection
+		default:
+		}
+
+		if nc == nil || !nc.IsConnected() {
+			log.Println("Connection not ready")
+			time.Sleep(200 * time.Millisecond)
+			continue
+		}
+		break WaitForEstablishedConnection
+	}
+	if ctx.Err() != nil {
+		log.Fatal(ctx.Err())
+	}
+
+	for {
+		if nc.IsClosed() {
+			break
+		}
+		if err := nc.Publish("hello", []byte("world")); err != nil {
+			log.Println(err)
+			time.Sleep(1 * time.Second)
+			continue
+		}
+		log.Println("Published message")
+		time.Sleep(1 * time.Second)
+	}
+
+	// Disconnect and flush pending messages
+	if err := nc.Drain(); err != nil {
+		log.Println(err)
+	}
+	log.Println("Disconnected")
+}
+```