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 |