Deprecate well-known role ids and introduce SeqConnection.Roles

src/Seq.Api/Model/Security/WellKnownRole.cs

@@ -1,5 +1,8 @@
-namespace Seq.Api.Model.Security
+using System;
+
+namespace Seq.Api.Model.Security
 {
+    [Obsolete("It's recommended that new code look up roles by name in `SeqConnection.Roles`.")]
     public static class WellKnownRole
     {
         public const string AdministratorRoleId = "role-administrator";

src/Seq.Api/ResourceGroups/EventsResourceGroup.cs

@@ -247,7 +247,7 @@ public async Task<DeleteResultPart> DeleteInSignalAsync(
         }
 
         /// <summary>
-        /// Connect to the live event stream. Dispose the resulting stream to disconnect.
+        /// Connect to the live event stream, read as strongly-typed objects. Dispose the resulting stream to disconnect.
         /// </summary>
         /// <typeparam name="T">The type into which events should be deserialized.</typeparam>
         /// <param name="signal">If provided, a signal expression describing the set of events that will be filtered for the result.</param>
@@ -256,6 +256,8 @@ public async Task<DeleteResultPart> DeleteInSignalAsync(
         /// <param name="cancellationToken">Token through which the operation can be cancelled.</param>
         /// <returns>An observable that will stream events from the server to subscribers. Events will be buffered server-side until the first
         /// subscriber connects, ensure at least one subscription is made in order to avoid event loss.</returns>
+        /// <remarks>See <a href="https://docs.datalust.co/docs/posting-raw-events#section-compact-json-format">the Seq ingestion
+        /// docs</a> for event schema information.</remarks>
         public async Task<ObservableStream<T>> StreamAsync<T>(
             SignalExpressionPart signal = null,
             string filter = null,
@@ -270,15 +272,16 @@ public async Task<ObservableStream<T>> StreamAsync<T>(
         }
 
         /// <summary>
-        /// Retrieve a list of events that match a set of conditions. The complete result is buffered into memory,
-        /// so if a large result set is expected, use InSignalAsync() and lastReadEventId to page the results.
+        /// Connect to the live event stream, read as raw JSON documents. Dispose the resulting stream to disconnect.
         /// </summary>
         /// <param name="signal">If provided, a signal expression describing the set of events that will be filtered for the result.</param>
         /// <param name="filter">A strict Seq filter expression to match (text expressions must be in double quotes). To
         /// convert a "fuzzy" filter into a strict one the way the Seq UI does, use connection.Expressions.ToStrictAsync().</param>
         /// <param name="cancellationToken">Token through which the operation can be cancelled.</param>
         /// <returns>An observable that will stream events from the server to subscribers. Events will be buffered server-side until the first
         /// subscriber connects, ensure at least one subscription is made in order to avoid event loss.</returns>
+        /// <remarks>See <a href="https://docs.datalust.co/docs/posting-raw-events#section-compact-json-format">the Seq ingestion
+        /// docs</a> for event schema information.</remarks>
         public async Task<ObservableStream<string>> StreamDocumentsAsync(
             SignalExpressionPart signal = null,
             string filter = null,

src/Seq.Api/ResourceGroups/RolesResourceGroup.cs

@@ -0,0 +1,55 @@
+// Copyright 2019 Datalust and contributors. 
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using System.Threading;
+using Seq.Api.Model.Security;
+
+namespace Seq.Api.ResourceGroups
+{
+    /// <summary>
+    /// Perform operations on user roles.
+    /// </summary>
+    public class RolesResourceGroup : ApiResourceGroup
+    {
+        internal RolesResourceGroup(ISeqConnection connection)
+            : base("Roles", connection)
+        {
+        }
+
+        /// <summary>
+        /// Find a role given its id.
+        /// </summary>
+        /// <param name="id">The id of a role to find.</param>
+        /// <param name="cancellationToken"><see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>The matching role.</returns>
+        public async Task<RoleEntity> FindAsync(string id, CancellationToken cancellationToken = default)
+        {
+            if (id == null) throw new ArgumentNullException(nameof(id));
+            return await GroupGetAsync<RoleEntity>("Item", new Dictionary<string, object> { { "id", id } }, cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// List all roles.
+        /// </summary>
+        /// <param name="cancellationToken"><see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>A list containing all roles available on the server.</returns>
+        public async Task<List<RoleEntity>> ListAsync(CancellationToken cancellationToken = default)
+        {
+            return await GroupListAsync<RoleEntity>("Items", cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

src/Seq.Api/SeqConnection.cs

@@ -141,6 +141,11 @@ public SeqConnection(string serverUrl, string apiKey = null, bool useDefaultCred
         /// </summary>
         public UsersResourceGroup Users => new UsersResourceGroup(this);
 
+        /// <summary>
+        /// Perform operations on user roles.
+        /// </summary>
+        public RolesResourceGroup Roles => new RolesResourceGroup(this);
+
         /// <summary>
         /// Perform operations on workspaces.
         /// </summary>