Document stream ID limitations and conventions in manual. Fixes #40 F…

…ixes #19

doc/ringserver.1

@@ -244,6 +244,29 @@ during SeedLink negotiation using the '?' and '*' characters for
 single or multiple character matches respectively.  Not all SeedLink
 clients support wild-carded network and station codes.
 
+.SH "Stream IDs"
+
+Each unique data stream is identified by a stream ID.  The stream ID
+can be arbitrary but is commonly a combination of a data source
+identifier and a suffix (separated by a slash) that identifies the
+the payload type.  For example:
+
+"FDSN:IU_COLA_00_B_H_Z/MSEED"
+
+For SeedLink protocol support, data source IDs should be valid FDSN
+Source IDs (https://docs.fdsn.org/projects/source-identifiers).
+
+The stream ID suffix recommendations are as follows:
+
+.nf
+  \fBMSEED\fP   : miniSEED v2 data records
+  \fBMSEED3\fP  : miniSEED v3 data records
+  \fBJSON\fP    : JSON payloads
+  \fBTEXT\fP    : Text payloads, where UTF-8 is assumed
+.fi
+
+The maximum length of stream IDs supported by the server is 59 bytes.
+
 .SH "Multi-protocol Support"
 
 Network listening ports can respond to all supported protocols

doc/ringserver.md

@@ -8,6 +8,7 @@
 1. [Config File Parameters](#config-file-parameters)
 1. [Access Control](#access-control)
 1. [Seedlink Support](#seedlink-support)
+1. [Stream Ids](#stream-ids)
 1. [Multi-Protocol Support](#multi-protocol-support)
 1. [Http Support](#http-support)
 1. [Transfer Logging](#transfer-logging)
@@ -164,6 +165,25 @@ ringserver [options] [configfile]
 
 <p >This server supports the wild-carding of network and station codes during SeedLink negotiation using the '?' and '*' characters for single or multiple character matches respectively.  Not all SeedLink clients support wild-carded network and station codes.</p>
 
+## <a id='stream-ids'>Stream Ids</a>
+
+<p >Each unique data stream is identified by a stream ID.  The stream ID can be arbitrary but is commonly a combination of a data source identifier and a suffix (separated by a slash) that identifies the the payload type.  For example:</p>
+
+<p >"FDSN:IU_COLA_00_B_H_Z/MSEED"</p>
+
+<p >For SeedLink protocol support, data source IDs should be valid FDSN Source IDs (https://docs.fdsn.org/projects/source-identifiers).</p>
+
+<p >The stream ID suffix recommendations are as follows:</p>
+
+<pre >
+  <b>MSEED</b>   : miniSEED v2 data records
+  <b>MSEED3</b>  : miniSEED v3 data records
+  <b>JSON</b>    : JSON payloads
+  <b>TEXT</b>    : Text payloads, where UTF-8 is assumed
+</pre>
+
+<p >The maximum length of stream IDs supported by the server is 59 bytes.</p>
+
 ## <a id='multi-protocol-support'>Multi-Protocol Support</a>
 
 <p >Network listening ports can respond to all supported protocols (SeedLink, DataLink and HTTP) for non-TLS ports.  The first command received by the server is used to determine which protocol is being used by the client, all subsequent communication is expected in this protocol.  Listening ports configured for TLS encryption can only support a single protocol that must be specified.</p>

src/http.c

@@ -946,9 +946,6 @@ GenerateID (ClientInfo *cinfo, const char *path, char **response, MediaType *typ
  * Generate stream list and place into buffer, which will be allocated
  * to the length needed and should be free'd by the caller.
  *
- * If 'timeextents' is true the earliest and latest times will be
- * included in the output.  For now this only works when level > 0.
- *
  * Check for 'match' parameter in 'path' and use value as a regular
  * expression to match against stream identifiers.
  *
@@ -1028,8 +1025,8 @@ GenerateStreams (ClientInfo *cinfo, const char *path, char **response, MediaType
       streamcount = yyjson_arr_size (stream_array);
 
       /* Allocate stream list buffer with maximum expected:
-       * for level-specific output, maximum per entry is 60 characters + newline
-       * otherwise the maximum per entry is 60 + 2x32 (time strings) plus a few spaces and newline */
+       * for /streamids output, maximum per entry is 60 characters + newline
+       * for /streams output, maximum per entry is 60 + 2x32 (time strings) plus a few spaces and newline */
       streamlistsize = (just_ids) ? 64 : 124;
       streamlistsize *= streamcount;