nats-io / nats-site Goto Github PK

"NATS Clients" section: It would be nice if there were recommended community clients for languages not directly supported by Apcera. Similar to how Redis does it. This wouldn't imply that Apcera supports these, but would make a developer feel much more comfortable downloading a third-party client.

"NATS use cases" section: Where possible, brief, plain-English examples of the bullet points would help people understand the capabilities, and would be more likely to cause them to continue reading and download NATS. Also, typo: "High througput message fanout" (missing "h" in throughput).

There are a number of inaccuracies and grammar errors in the document that need to be cleaned up.

• Need to remove second-person narrative ("you [...]") in multiple places.
• Link to the Protocol Guide as the authoritative source for specific syntax and meaning, vs. re-defining it, possibly in a conflicting or confusing way, here.
• Re-focus the document on the 5,000 foot view of client structure and conventions, possibly including some FAQs that are client-dev specific, e.g.: Why do you send a PING-PONG during the CONNECT sequence?

Step 3: "CD to the gnatsd directory you cloned." cd $GOPATH/src/github.com/nats-io/gnatsd
Wrong. . . This directory does not exists in the source tree.

Step 4: "View the NATS server source code." Use command ls to list the gnatsd.go file.
Use command cat gnatsd.go to view the code.
Wrong. . . The file gnatsd.go does not exists in the cloned source repo.

See:

C:\Programs\Go\src\github.com\nats-io>dir gnatsd.go /s
 Volume in drive C is Windows
 Volume Serial Number is ACA3-EE57
File Not Found

That makes the rest of instructions at "http://nats.io/documentation/tutorials/nats-source/" useless.

Setup custom error pages, including Analytics to track 404s:
http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html

Hi all 👋

I was trying to follow the Explore NATS Queueing but it seems to be outdated since the client libraries aren't shipped with the main NATS Server code.

I'm going to submit a PR to fix this.

🎉

I'm trying to follow the benchmark instructions here and the java steps seem to fail with lots of "cannot find symbol" errors.

I don't know anything about Java, but I was able to compile the source files in step 1 by specifying a sourcepath and classpath:

javac -d ./bin -sourcepath ./src/main/java/org/nats/*.java -cp /Users/x/.m2/repository/org/slf4j/slf4j-api/1.7.14/slf4j-api-1.7.14.jar

However now on the next step javac -d ./bin ./src/test/java/org/nats/benchmark/*.java

I'm getting additional errors:

./src/test/java/org/nats/benchmark/PubPerf.java:17: error: cannot find symbol
                Connection conn = Connection.connect(prop);
                ^
  symbol:   class Connection
  location: class PubPerf
./src/test/java/org/nats/benchmark/PubPerf.java:17: error: cannot find symbol
                Connection conn = Connection.connect(prop);
                                  ^
  symbol:   variable Connection
  location: class PubPerf
./src/test/java/org/nats/benchmark/PubSubPerf.java:18: error: cannot find symbol
                final Connection conn1 = Connection.connect(new Properties());
                      ^
  symbol:   class Connection
  location: class PubSubPerf
./src/test/java/org/nats/benchmark/PubSubPerf.java:18: error: cannot find symbol
                final Connection conn1 = Connection.connect(new Properties());
                                         ^
  symbol:   variable Connection
  location: class PubSubPerf
./src/test/java/org/nats/benchmark/PubSubPerf.java:19: error: cannot find symbol
                final Connection conn2 = Connection.connect(new Properties());
                      ^
  symbol:   class Connection
  location: class PubSubPerf
./src/test/java/org/nats/benchmark/PubSubPerf.java:19: error: cannot find symbol
                final Connection conn2 = Connection.connect(new Properties());
                                         ^
  symbol:   variable Connection
  location: class PubSubPerf

I also tried specifying various combinations of classpath/sourcepath, but it didn't work. I'm guessing javac just needs to know the classpath for Connection, but i'm not too sure where that is. Is there an easy way of getting the benchmarks up and running?

On the docker docs site It says there is an example client that can be used to test the docker gnats container. However it only shows a path but not where the path comes from.

It says the executable would be in: cd /nats-docs/tutorials/examples/

I assume without testing that a vanilla Ubuntu 16.04 computer won't have a root directory called /nats-docs/ (bold assumption, I know ;) ).

Also one might wonder why it's not just possible to "docker run nats-ping-example" or similar.

From @htrob
"The NATS website can be a bit confusing and newcomers have a hard time figuring out what are the differences between NATS and NATS Streaming, what's STAN and when to use either. A feature set matrix for each side by side and clear definition of terms upfront should clear the difficulty/inconsistencies/fuzziness"

Had a particular hard time figuring out how clients and server "under the hood" communications go, and how to set ping options in order to have prompt reconnection or awareness of failures.

The clustering documentation contains everything necessary to set up a cluster.

However, it requires reading about half the page to understand the basics of how it works. If the first paragraph contained something like the following, it would help people get started more quickly.

In addition to a port for listening for clients, gnatsd can listen on a "cluster" URL (the -cluster option). Additional gnatsd servers can then add that URL to their -routes argument to join the cluster.

Examples:

Without clustering:

gnatsd -p 4222

Simple clustering:

# server A on 10.10.0.1
gnatsd -p 4222 -cluster nats://10.10.0.1:5222

# server B on 10.10.0.2
gnatsd -p 4222 -routes nats://10.10.0.1:5222

Server B may also serve a "cluster" URL, and Server A may add that to its routes. However it is not required to do this; once a server connects to the cluster it becomes aware of all other servers in that cluster.

# server A on 10.10.0.1
gnatsd -p 4222 -cluster nats://10.10.0.1:5222 -routes nats://10.10.0.2:5222

# server B on 10.10.0.2
gnatsd -p 4222 -cluster nats://10.10.0.2:5222 -routes nats://10.10.0.1:5222 

Clients connecting to any server in the cluster will remain connected to the cluster even if the server it originally connected to is taken down, as long as at least a single server remains.

Documentation for the gnatsd config should specify default values for properties that are required.

Alternatively, the example config can be updated to reflect the defaults for required properties.

This is a common practice in ops. It's not instinctive to visit the gnatsd godoc to figure out what the defaults are.

Provide a process for users to add their logo. This could be instructions to email our "info" email address and we add the logo or instructions/Walkthrough for a PR. IMO instructions to email us with guidance on logo sizes, types, etc, would be easiest for our users.

We need a guide to troubleshooting NATS. This can include:

• Enabling server tracing/debugging, what to look for.
• Verifying client connectivity to the server
• Troubleshooting TLS
• Client side instrumentation (error and connection callbacks)

http://www.nats.io/documentation/tutorials/nats-queueing is referring to nats-sub as taking a queue name argument. This is wrong for both node and go clients and perhaps the others.

/cc @bjflanne @lparis

From personal experience and talking to @chriscasper, keeping the site, docs and theme in 3 separate repos is unnecessarily cumbersome for contributors/collaborators and also in terms of publishing the site. Is there any reason we can't combine all this back into a single repo: nats-site? I don't see any down-side.

add https://github.com/byrnedo/php-nats-streaming

to download page:
http://nats.io/download/:

From @Signull on January 11, 2017 16:22

Hello @derekcollison

I love NATS however the company I work for wont go with it because they do not see obvious documentation about HA, CLUSTERING, and in addition they want to see a performance shocker. I know that as its written in GO its already performing at a much better rate. However adding a selling point in picture/graphs setting, showing how much more operations NATS can perform against Kafka on a per node basis would be an amazing selling point. Lastly add a whole bunch of QA to stack overflow. It looks like there isn't a community behind this and it scares people away.

Sincerely "someone who thinks that kafka, zookeeper, and all its other toolings are archaic when it comes to setup and usage."

AKA The DevOps Senpai.

I AM BEGGING YOU TO SUCCEED.

Copied from original issue: nats-io/go-nats#251

We should provide some guidance on when to use which store.

Memory

• Pure speed
• Do not require at least once delivery guarantees. This may be for use cases where NATS streaming if being used fo it's features (e.g. replay, rate limiting) rather than persistence requirements, and the system can rebuild state upon failure.

File

• Require at least once delivery.
• High throughput requirements and moderate number of channels

Database

• Have strong requirements around data backup
• High number of channels
• Moderate/Low throughput requirements.

CC @kozlovic for comment.

Note, saving off this content here until the site is refactored (otherwise I'd have just submitted a PR).

The request repy example page ( http://nats.io/documentation/tutorials/nats-req-rep/ ) has outdated information. For one, no nats-docs repository exists, the go client doesn't have nats-rep either. nats-req seems to require subject and message

Review past requests for design patterns and add these as a section to the documentation. One that frequently occurs is a coordinator/worker architecture (request to unknown # of subscribers, then select one to do work based on criteria in the response).

Would it be possible to include a sample conversation for the examples under concepts? Specifically but not limited to Request Reply. I would like to be able to test these concepts in telnet to get a better idea of how they work.

Examples

-The relationship between NATS Streaming and NATS Server - esp operationally WRT to if somebody is already running NATS Server what should they do.

-How to create a connection - some users eventually figured out you have to create a plain NATS connection first, but still are not sure they are doing it the best/simplest way.

The NATS Server clustering protocol duplicates most of the NATS protocol page. These can be consolidated to avoid duplication. If any protocol message has a special meaning when exchanged between servers (vs. between client and server), it should be noted in the main document.

The section here says that we have a limit of 2^32 subjects. This is no longer the case since v0.8.0. This need to be updated.

I'm assuming it's an acronym since it's in all-caps, but I can't find anywhere on the site where it defines the acronym. Maybe an FAQ can be added?

Hi,
I have a few questions regarding the functionality of NATS. Is it possible to send and receive .txt, .doc, or any other files directly using NATS? I saw in the documentation page that NATS server treats all messages as byte arrays (https://nats.io/documentation/writing_applications/publishing/). And some libraries may provide helpers to convert other data formats to and from bytes. If its possible to send and receive other formats of messages or files as such, then how can I do that? Please provide any documentation. Also is there any detailed design manual of NATS publicly available for beginners to understand the design concepts underlying the messaging system?

https://github.com/nats-io/nats-site/blob/master/content/documentation/streaming/nats-streaming-install.md links to a non-existent docker image.

Temporarily removing sentence pointing there.

The #of stars is also being populated for the #of watchers and forks for NATS Server and NATS Streaming, instead of showing the accurate numbers.

From @monopollly on November 22, 2016 14:35

Could you please write a hardware preferences for nats...

something like this:
https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html

Thanks!

Copied from original issue: nats-io/nats-server#380

We should have a section in the documentation focusing on subject usage and wildcards.

A good place in the documentation could be a new list item under concepts, near publish/subscribe.

Content can be garnered from:
https://github.com/nats-io/nats#wildcard-subscriptions
https://github.com/nats-io/csnats#wildcard-subscriptions
https://groups.google.com/forum/#!topic/natsio/zeQKbVNi0rc
https://groups.google.com/forum/#!topic/natsio/z12Afncvslc
https://groups.google.com/forum/#!topic/natsio/4hIGmO48ERQ

@lparis, if you can get to this, that'd be great, otherwise I will when I get a chance.

I get the following errors after running hugo server -w --port=1414 --theme=nats --buildDrafts:

ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 Error while rendering page clients.html: template: clients/single.html:7:16: executing "clients/single.html" at <$.Site.Data.clients>: Data is not a field of struct type *hugolib.SiteInfo
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 Error while rendering page download.html: html/template: "download/single.html" is an incomplete template
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: theme/partials/header.html:2:20: executing "theme/partials/header.html" at <.Site.BaseURL>: BaseURL is not a field of struct type *hugolib.SiteInfo in theme/partials/header.html
ERROR: 2016/01/06 template: partials/quick-view.html:5:14: executing "partials/quick-view.html" at <$.Site.Data.clients>: Data is not a field of struct type *hugolib.SiteInfo in partials/quick-view.html

The server is able to run and serve on port 1414; however, there seem to be missing partials and styles. Any insights?

Edit: This is on Mac OS X with hugo installed via homebrew. This is the output of hugo version:

Hugo Static Site Generator v0.13-DEV buildDate: 2015-01-16T00:28:45-08:00

Have a dropdown or link for the user to choose what version of the software to view documentation for.

Document installing the NATS server from other channels.

homebrew (http://brewformulas.org/Gnatsd):
brew install gnatsd

Chocolately (https://chocolatey.org/packages/gnatsd):
choco install gnatsd

• Include some of the great examples @bruth had in his blog post (https://dev.to/byronruth/use-cases-for-persistent-logs-with-nats-streaming)

• We say in the docs 'Support for various messaging models and use cases (flexible)' - many would find a few examples useful there.. likewise, in the NATS Use Cases section on /doc page having an actual example to build on each scenario listed would really help. << via @ipedrazas

We should add all the information that is in the Clients page to the Download page, and do away with the separate Clients page and menu item.

The Downloads page should simply have a Server section (with the gnatsd links) and Clients section (with all the client info/links).

/cc @derekcollison @chriscasper

This link needs to be fixed. No content appears about the download.

Hello,
in this page a link to the Python client is missing.
Only the link to a third party lib is provided and travis reports that it doesn't compile.

But on the Download page the Python clients are listed.

The absence of a python client would have been a show stopper for us. I was lucky I didn't stop my investigation at the first page. Could you please fix this nats-client page ?

Based on some recurrent feedback from developer community, enhance documentation to cover topics of interest after initial set up of NATS. Examples include:

• Sizing NATS (single node and Clusters)
• Upgrading NATS (especially when clustered in an "always" on scenario)
• Troubleshooting NATS (what to look for in the logs, what to expect with debug or trace output, etc)

See also nats-io/stan.java#40

seems better than the current one your recommending

This is he one you have in the releases.yaml
https://github.com/jedisct1/rust-nats

This is the one i have found to be more mature.
https://github.com/brianshannan/nats-rs

Hello, I have one question, maybe I misunderstood the messaging-bus concept.
I'm using microservice architecture (stateless) with REST APIs. E.g. when an API is called then during the processing I want to access a bus-system and i want to get newest data for a certain topic. it's just possible when the message on the queue keeps as long as new message will be published. It means the message can not be deleted, only publishing of new data on the topic can rewrite the data => similar to redis (hashmap).

The problem in microservice architecture is that callback functions are useless, because as i said this is stateless architecture. What would be the solution by using nats? Thanks!

Getting "*.nats.io" certificate name does not match input when visiting the site on all browsers and also on mobile.

As pointed out in #182, the NATS Clients page duplicates a subset of the information contained on the Download page, which is usually guaranteed to be up-to-date.

We should keep the Download page as the authoritative, up-to-date resource for information on the server and clients, and retire the separate NATS Clients page.

@ColinSullivan1 @kozlovic @aricart @bjflanne @wallyqs @derekcollison please weigh in

Did not find a section on TLS. Precisely, several users already had issues due to the lack of understanding that even when servers and clients are configured to use TLS, the beginning of the protocol is done in plain text.

Some info sent to an user on slack:

The beginning of the protocol exchange between server and client is done in plain text.
When the client creates the TCP connection, the server will, in response, send in plain text its “INFO” protocol message.
From this protocol, the client knows if the server requires or not TLS. If the client is not configured for TLS and server asks, the connect will fail before even attempting to send anything to the server.
And vice-versa.
If server and client are configured for TLS, the client, after receiving the INFO protocol, will switch the connection to TLS and then send its CONNECT protocol.

The new go nrpc url is https://github.com/nats-rpc/

Also, the author does not correspond to someone I know, and the initial author is @mdevan. (@mdevan could you confirm if Cameron Sparr is related to the project ?)

Last but not least, nrpc now has a python port (https://github.com/nats-rpc/python-nrpc). I suggest changing the second sentence of the description to:

"It can generate a Go or Python client and server from [...]"

The documentation listed here says that the following commands should subscribe to the "foo" subject on the "my-queue" queue.

cd $GOPATH/src/github.com/nats-io/nats/examples
go run nats-sub.go foo my-queue

However, looking at the code for nats-sub.go, it looks like the second argument is ignored, resulting in all the clients receiving the published message, when what was expected was that only one client would receive the message.

However, the Python client works as expected.

python examples/nats-sub foo -q my-queue

Suggestion: expand documentation to add examples or best practices for naming workers, subjects.

Alongside the documentation, I propose we add a tutorials section. This section could contain content such as:

• Step by Step application development using various NATS clients
• Walkthroughs of server deployment, setting up routes, etc.
• Using / Developing NATS connectors
• A walkthrough of the process of making a contribution, where to find what to do, and what to expect throughout the process.

... and update the appropriate links referencing the old name.