taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

review of syntax and grammar

Browse Source
This commit is contained in:
Ginger Collison 2021-02-25 10:12:48 -06:00 committed by GitHub
parent 2dc6e3d5d0
commit 442badf74f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 17 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
nats-server/configuration/mqtt/README.md
View File

@ -2,9 +2,9 @@
*Supported since NATS Server version 2.2* *Supported since NATS Server version 2.2*
NATS follows as close as possible the MQTT v3.1.1 [specification](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html). NATS follows as closely as possible to the MQTT v3.1.1 [specification](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html).
## When to use MQTT ## When to Use MQTT
MQTT support in NATS is intended to be an enabling technology allowing users to leverage existing MQTT support in NATS is intended to be an enabling technology allowing users to leverage existing
investments in their IoT deployments. Updating software on the edge or endpoints can be onerous investments in their IoT deployments. Updating software on the edge or endpoints can be onerous
@ -18,14 +18,14 @@ good choice to use end to end, including use on resource constrained devices.
In existing MQTT deployments or in situations when endpoints can only support MQTT, using a NATS server In existing MQTT deployments or in situations when endpoints can only support MQTT, using a NATS server
as a drop-in MQTT server replacement to securely connect to a remote NATS cluster or supercluster is as a drop-in MQTT server replacement to securely connect to a remote NATS cluster or supercluster is
compelling. You can keep your existing IoT investment and use NATS for secure, resilient, and compelling. You can keep your existing IoT investment and use NATS for secure, resilient, and
scalable access to your streams and services. scalable access to your streams and services.
## JetStream Requirements ## JetStream Requirements
In order for an MQTT client to connect to the NATS Server, the user's account must be JetStream enabled. For an MQTT client to connect to the NATS server, the user's account must be JetStream enabled.
This is because persistence is needed for the sessions and retained messages (since even retained messages This is because persistence is needed for the sessions and retained messages since even retained messages
of QoS 0 are persisted). of QoS 0 are persisted.
## MQTT Topics and NATS Subjects ## MQTT Topics and NATS Subjects
@ -72,9 +72,9 @@ The wildcard `+` matches a single level, which means `foo/+` can receive message
`foo/baz`, but not on `foo/bar/baz` nor `foo`. This is the same with NATS subscriptions using `foo/baz`, but not on `foo/bar/baz` nor `foo`. This is the same with NATS subscriptions using
the wildcard `*`. Therefore `foo/+` would translate to `foo.*`. the wildcard `*`. Therefore `foo/+` would translate to `foo.*`.
## Communication between MQTT and NATS ## Communication Between MQTT and NATS
When an MQTT client creates a subscription on a topic, the NATS Server creates the similar When an MQTT client creates a subscription on a topic, the NATS server creates the similar
NATS subscription (with conversion from MQTT topic to NATS subject) so that the interest NATS subscription (with conversion from MQTT topic to NATS subject) so that the interest
is registered in the cluster and known to any NATS publishers. is registered in the cluster and known to any NATS publishers.
@ -106,13 +106,13 @@ The total of subscriptions' `max_ack_pending` on a given session cannot exceed 6
to create a subscription that would bring the total above the limit would result in the server to create a subscription that would bring the total above the limit would result in the server
returning a failure code in the SUBACK for this subscription. returning a failure code in the SUBACK for this subscription.
Due to how the NATS Server handles the MQTT "`#`" wildcard, each subscription ending with "`#`" Due to how the NATS server handles the MQTT "`#`" wildcard, each subscription ending with "`#`"
will use 2 times the `max_ack_pending` value. will use 2 times the `max_ack_pending` value.
## Sessions ## Sessions
NATS Server will persist all sessions, even if they are created with the "clean session" flag, which means NATS Server will persist all sessions, even if they are created with the "clean session" flag, meaning
that session last only for the duration of the network connection between the client and the server. that sessions only last for the duration of the network connection between the client and the server.
A session is identified by a client identifier. If two connections try to use the same client identifier, A session is identified by a client identifier. If two connections try to use the same client identifier,
the server, per specification, will close the existing connection and accept the new one. the server, per specification, will close the existing connection and accept the new one.
@ -120,7 +120,7 @@ the server, per specification, will close the existing connection and accept the
If the user incorrectly starts two applications that use the same client identifier, this would result If the user incorrectly starts two applications that use the same client identifier, this would result
in a very quick flapping if the MQTT client has a reconnect feature and quickly reconnects. in a very quick flapping if the MQTT client has a reconnect feature and quickly reconnects.
To prevent this, the NATS Server will accept the new session and will delay the closing of the To prevent this, the NATS server will accept the new session and will delay the closing of the
old connection to reduce the flapping rate. old connection to reduce the flapping rate.
Detection of the concurrent use of sessions also works in cluster mode. Detection of the concurrent use of sessions also works in cluster mode.
@ -138,17 +138,16 @@ A PUBLISH Packet with a RETAIN flag set to 1 and a payload containing zero bytes
NATS supports MQTT in a NATS cluster. The replication factor is automatically set based on the size NATS supports MQTT in a NATS cluster. The replication factor is automatically set based on the size
of the cluster. of the cluster.
### Connections with same client ID ### Connections with Same Client ID
If a client is connected to a server "A" in the cluster and another client connects to a server "B" and If a client is connected to a server "A" in the cluster and another client connects to a server "B" and
uses the same client identifier, server "A" will close its client upon discovering the use of uses the same client identifier, server "A" will close its client connection upon discovering the use of
an active client identifier. an active client identifier.
Of course, this is not as easy and immediate than if the two applications are connected to the same server. Users should avoid this situation as this is not as easy and immediate as if the two applications are connected to the same server.
So users should avoid as much as possible this situation.
There may be cases where the server will reject the new connection if there is no safe way to There may be cases where the server will reject the new connection if there is no safe way to
close the existing connection if it is in the middle of processing some MQTT packets. close the existing connection, such as when it is in the middle of processing some MQTT packets.
### Retained Messages ### Retained Messages
@ -169,6 +168,6 @@ it will close the connection.
- MQTT published messages on topic names containing "` `" or "`.`" characters will cause the - MQTT published messages on topic names containing "` `" or "`.`" characters will cause the
connection to be closed. Presence of those characters in MQTT subscriptions will result in error connection to be closed. Presence of those characters in MQTT subscriptions will result in error
code in the SUBACK packet. code in the SUBACK packet.
- MQTT wildcard `#` may cause the NATS Server to create two subscriptions. - MQTT wildcard `#` may cause the NATS server to create two subscriptions.
- MQTT concurrent sessions may result in the new connection to be evicted instead of the existing one. - MQTT concurrent sessions may result in the new connection to be evicted instead of the existing one.
- MQTT retained messages in clustering mode is best effort. - MQTT retained messages in clustering mode is best effort.