From 30514de2742730d975ebacee4bb4da5efd44aad5 Mon Sep 17 00:00:00 2001 From: Colin Sullivan Date: Thu, 13 May 2021 14:40:42 -0600 Subject: [PATCH 1/5] Add section on naming streams, consumers, and accounts Signed-off-by: Colin Sullivan --- SUMMARY.md | 1 + jetstream/administration/naming.md | 19 +++++++++++++++++++ jetstream/concepts/consumers.md | 2 +- jetstream/concepts/streams.md | 2 +- 4 files changed, 22 insertions(+), 2 deletions(-) create mode 100644 jetstream/administration/naming.md diff --git a/SUMMARY.md b/SUMMARY.md index c5a2046..b155db7 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -127,6 +127,7 @@ * [Using Source](jetstream/getting_started/using_source.md) * [Administration & Usage from CLI](jetstream/administration/README.md) * [Account Information](jetstream/administration/account.md) + * [Naming Streams, Consumers, and Accounts](jetstream/administration/naming.md) * [Streams](jetstream/administration/streams.md) * [Consumers](jetstream/administration/consumers.md) * [Monitoring](jetstream/monitoring.md) diff --git a/jetstream/administration/naming.md b/jetstream/administration/naming.md new file mode 100644 index 0000000..385b626 --- /dev/null +++ b/jetstream/administration/naming.md @@ -0,0 +1,19 @@ +# Stream, Consumer, and Account Names + +Stream, Consumer (durable name), and Account names are used in both the +subject namespace used by JetStream and the filesystem backing JetStream +persistence. This means that when naming streams, consumers, and +accounts, names must adhere to subject naming rules as well as being +friendly to the file system. + +We recommend the following guideline for stream, consumer, and account names: + +* Alphanumeric values are recommended. +* Spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\) are prohibited. +* Limit names to 255 characters or less. +* Do not use reserved file names like NUL, LPT1, etc. +* Be aware that some file systems are case insentitive so do not + use stream or account names that would collide in a file system. + For example, `Foo` and `foo` would collide on a Windows or Mac OSx System. + + We plan to address these limitations in a future release. \ No newline at end of file diff --git a/jetstream/concepts/consumers.md b/jetstream/concepts/consumers.md index cbfd431..ff2dff3 100644 --- a/jetstream/concepts/consumers.md +++ b/jetstream/concepts/consumers.md @@ -22,7 +22,7 @@ When defining Consumers the items below make up the entire configuration of the | AckWait | How long to allow messages to remain un-acknowledged before attempting redelivery | | DeliverPolicy | The initial starting mode of the consumer, `DeliverAll`, `DeliverLast`, `DeliverNew`, `DeliverByStartSequence` or `DeliverByStartTime` | | DeliverySubject | The subject to deliver observed messages. Useful to setup an alternate subject for a regular NatsSubcriber can listen on that subject. Not allowed for pull subscriptions. | -| Durable | The name of the Consumer, which the server will track, allowing resuming consumption where left off. | +| Durable | The name of the Consumer, which the server will track, allowing resuming consumption where left off. See [naming](../../administration/naming.md].| | FilterSubject | When consuming from a Stream with many subjects, or wildcards, select only a specific incoming subjects, supports wildcards | | MaxDeliver | Maximum amount times a specific message will be delivered. Use this to avoid poison pills crashing all your services forever | | OptStartSeq | When first consuming messages from the Stream start at this particular message in the set | diff --git a/jetstream/concepts/streams.md b/jetstream/concepts/streams.md index e4e7aef..eaa0373 100644 --- a/jetstream/concepts/streams.md +++ b/jetstream/concepts/streams.md @@ -16,7 +16,7 @@ When defining Streams the items below make up the entire configuration of the se | Item | Description | | :--- | :--- | -| Name | A name for the Stream that may not have spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\) | +| Name | A name for the Stream that may not have spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\). See [naming](../administration/naming.md] | | Storage | The type of storage backend, `File` and `Memory` | | Subjects | A list of subjects to consume, supports wildcards | | Replicas | How many replicas to keep for each message in a clustered JetStream, maximum 5 | From 0b1886871c07d9ecf6469e19dfa79a9e033a3e26 Mon Sep 17 00:00:00 2001 From: Ginger Collison Date: Thu, 13 May 2021 16:56:58 -0500 Subject: [PATCH 2/5] syntax & grammar review --- jetstream/administration/naming.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jetstream/administration/naming.md b/jetstream/administration/naming.md index 385b626..c968572 100644 --- a/jetstream/administration/naming.md +++ b/jetstream/administration/naming.md @@ -9,11 +9,11 @@ friendly to the file system. We recommend the following guideline for stream, consumer, and account names: * Alphanumeric values are recommended. -* Spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\) are prohibited. +* Spaces, tabs, period \(`.`\), greater than \(`>`\) or asterisk \(`*`\) are prohibited. * Limit names to 255 characters or less. * Do not use reserved file names like NUL, LPT1, etc. * Be aware that some file systems are case insentitive so do not use stream or account names that would collide in a file system. For example, `Foo` and `foo` would collide on a Windows or Mac OSx System. - We plan to address these limitations in a future release. \ No newline at end of file + We plan to address these limitations in a future release. From 60f3fbb79fa5c1aa9c6d18b3d45321820e228b77 Mon Sep 17 00:00:00 2001 From: Ginger Collison Date: Thu, 13 May 2021 16:58:21 -0500 Subject: [PATCH 3/5] fix asterisk --- jetstream/concepts/streams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jetstream/concepts/streams.md b/jetstream/concepts/streams.md index eaa0373..296ba69 100644 --- a/jetstream/concepts/streams.md +++ b/jetstream/concepts/streams.md @@ -16,7 +16,7 @@ When defining Streams the items below make up the entire configuration of the se | Item | Description | | :--- | :--- | -| Name | A name for the Stream that may not have spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\). See [naming](../administration/naming.md] | +| Name | A name for the Stream that may not have spaces, tabs, period \(`.`\), greater than \(`>`\) or asterisk \(`*`\). See [naming](../administration/naming.md] | | Storage | The type of storage backend, `File` and `Memory` | | Subjects | A list of subjects to consume, supports wildcards | | Replicas | How many replicas to keep for each message in a clustered JetStream, maximum 5 | From d3324c138a36868c33115bda2c49f11c104b3904 Mon Sep 17 00:00:00 2001 From: Colin Sullivan Date: Fri, 14 May 2021 15:55:00 -0600 Subject: [PATCH 4/5] Additional guidance Signed-off-by: Colin Sullivan --- jetstream/administration/naming.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/jetstream/administration/naming.md b/jetstream/administration/naming.md index 385b626..f458d20 100644 --- a/jetstream/administration/naming.md +++ b/jetstream/administration/naming.md @@ -10,7 +10,9 @@ We recommend the following guideline for stream, consumer, and account names: * Alphanumeric values are recommended. * Spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\) are prohibited. -* Limit names to 255 characters or less. +* Limit name length. The JetStream storage directories will include the account, +stream name, and consumer name, so a generally safe approach would be to keep names +under 32 characters. * Do not use reserved file names like NUL, LPT1, etc. * Be aware that some file systems are case insentitive so do not use stream or account names that would collide in a file system. From c3308cfcc9033ad0578d2e6b58d2c9004921c3a8 Mon Sep 17 00:00:00 2001 From: Ginger Collison Date: Mon, 17 May 2021 09:23:35 -0500 Subject: [PATCH 5/5] fix typo <> insensitive --- jetstream/administration/naming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jetstream/administration/naming.md b/jetstream/administration/naming.md index 914c41e..4cd176c 100644 --- a/jetstream/administration/naming.md +++ b/jetstream/administration/naming.md @@ -19,7 +19,7 @@ under 32 characters. * Limit names to 255 characters or less. >>>>>>> 60f3fbb79fa5c1aa9c6d18b3d45321820e228b77 * Do not use reserved file names like NUL, LPT1, etc. -* Be aware that some file systems are case insentitive so do not +* Be aware that some file systems are case insensitive so do not use stream or account names that would collide in a file system. For example, `Foo` and `foo` would collide on a Windows or Mac OSx System.