Merge pull request #135 from liammclennan/add-expression-indexes

Add expression indexes

Author: liammclennan

src/Seq.Api/Model/Indexes/IndexEntity.cs

@@ -0,0 +1,33 @@
+    namespace Seq.Api.Model.Indexes
+{
+    /// <summary>
+    /// An index over the event stream. May be one of several types discriminated by <see cref="IndexedEntityType"/>.
+    /// </summary>
+    public class IndexEntity: Entity
+    {
+        /// <summary>
+        /// The `Id` of the associated entity (Signal, Alert or Expression index).
+        /// </summary>
+        public string IndexedEntityId { get; set; }
+        
+        /// <summary>
+        /// The type of this index.
+        /// </summary>
+        public IndexedEntityType IndexedEntityType { get; set; }
+
+        /// <summary>
+        /// The owner / creator of this index.
+        /// </summary>
+        public string OwnerUsername { get; set; }
+
+        /// <summary>
+        /// The name of this index. May not be applicable to all index types.
+        /// </summary>
+        public string Label { get; set; }
+
+        /// <summary>
+        /// The storage used by this index.
+        /// </summary>
+        public ulong StorageBytes { get; set; }
+    }
+}

src/Seq.Api/Model/Indexes/IndexedEntityType.cs

@@ -0,0 +1,23 @@
+namespace Seq.Api.Model.Indexes
+{
+    /// <summary>
+    /// The type of the index.
+    /// </summary>
+    public enum IndexedEntityType
+    {
+        /// <summary>
+        /// A predicate index for a signal expression.
+        /// </summary>
+        Signal,
+        
+        /// <summary>
+        /// An expression index.
+        /// </summary>
+        ExpressionIndex,
+        
+        /// <summary>
+        /// A predicate index for an alert filter.
+        /// </summary>
+        Alert,
+    }
+}

src/Seq.Api/Model/Indexing/ExpressionIndexEntity.cs

@@ -0,0 +1,18 @@
+namespace Seq.Api.Model.Indexing
+{
+    /// <summary>
+    /// An index based on an expression.
+    /// </summary>
+    public class ExpressionIndexEntity: Entity
+    {
+        /// <summary>
+        /// The expression to be indexed.
+        /// </summary>
+        public string Expression { get; set; }
+        
+        /// <summary>
+        /// A user-provided description of the index.
+        /// </summary>
+        public string Description { get; set; }
+    }
+}

src/Seq.Api/Model/Settings/SettingName.cs

@@ -15,6 +15,7 @@
 using System;
 using Seq.Api.Model.Apps;
 using Seq.Api.Model.Updates;
+using Seq.Api.Model.Users;
 using Seq.Api.ResourceGroups;
 
 namespace Seq.Api.Model.Settings
@@ -124,6 +125,16 @@ public enum SettingName
         /// Seq will stop accepting new events.
         /// </summary>
         MinimumFreeStorageSpace,
+        
+        /// <summary>
+        /// A dictionary of `(string, string)` pairs that will be used to initialize the
+        /// <see cref="UserEntity.Preferences"/> property when preparing new user entities
+        /// with <see cref="UsersResourceGroup.TemplateAsync"/>, and with automatically
+        /// provisioning SSO users (when enabled).
+        /// </summary>
+        /// <remarks>User preference keys are unconstrained; the Seq UI uses a number of these, but
+        /// alternative interfaces and integrations may add additional items to this collection.</remarks>
+        NewUserPreferences,
 
         /// <summary>
         /// A comma-separated list of role ids that will be assigned to new users by default.

src/Seq.Api/Model/Signals/SignalEntity.cs

@@ -67,6 +67,11 @@ public SignalEntity()
         /// If <c>true</c>, the signal can only be modified by users with the <see cref="Permission.Project"/> permission.
         /// </summary>
         public bool IsProtected { get; set; }
+        
+        /// <summary>
+        /// If <c>true</c>, the signal has no backing index.
+        /// </summary>
+        public bool IsIndexSuppressed { get; set; }
 
         /// <summary>
         /// How the signal is grouped in the Seq UI.

src/Seq.Api/ResourceGroups/ExpressionIndexesResourceGroup.cs

@@ -0,0 +1,60 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Seq.Api.Model;
+using Seq.Api.Model.Indexing;
+
+namespace Seq.Api.ResourceGroups
+{
+    /// <summary>
+    /// Perform operations on expression indexes.
+    /// </summary>
+    public class ExpressionIndexesResourceGroup: ApiResourceGroup
+    {
+        internal ExpressionIndexesResourceGroup(ILoadResourceGroup connection) : base("ExpressionIndexes", connection)
+        {
+        }
+        
+        /// <summary>
+        /// Retrieve expression indexes.
+        /// </summary>
+        /// <param name="cancellationToken"><see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>A list containing matching expression indexes.</returns>
+        public async Task<List<ExpressionIndexEntity>> ListAsync(CancellationToken cancellationToken = default)
+        {
+            return await GroupListAsync<ExpressionIndexEntity>("Items", cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Construct an expression index with server defaults pre-initialized.
+        /// </summary>
+        /// <param name="cancellationToken"><see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>The unsaved expression index.</returns>
+        public async Task<ExpressionIndexEntity> TemplateAsync(CancellationToken cancellationToken = default)
+        {
+            return await GroupGetAsync<ExpressionIndexEntity>("Template", cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Add a new expression index.
+        /// </summary>
+        /// <param name="entity">The expression index to add.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>The expression index, with server-allocated properties such as <see cref="Entity.Id"/> initialized.</returns>
+        public async Task<ExpressionIndexEntity> AddAsync(ExpressionIndexEntity entity, CancellationToken cancellationToken = default)
+        {
+            return await GroupCreateAsync<ExpressionIndexEntity, ExpressionIndexEntity>(entity, cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Remove an existing expression index.
+        /// </summary>
+        /// <param name="entity">The expression index to remove.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>A task indicating completion.</returns>
+        public async Task RemoveAsync(ExpressionIndexEntity entity, CancellationToken cancellationToken = default)
+        {
+            await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

src/Seq.Api/ResourceGroups/IndexesResourceGroup.cs

@@ -0,0 +1,58 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Seq.Api.Model.Alerting;
+using Seq.Api.Model.Indexes;
+using Seq.Api.Model.Indexing;
+using Seq.Api.Model.Signals;
+
+namespace Seq.Api.ResourceGroups
+{
+    /// <summary>
+    /// Statistics about indexes.
+    /// </summary>
+    public class IndexesResourceGroup : ApiResourceGroup
+    {
+        internal IndexesResourceGroup(ILoadResourceGroup connection)
+            : base("Indexes", connection)
+        {
+        }
+        /// <summary>
+        /// Retrieve the index with the given id; throws if the entity does not exist.
+        /// </summary>
+        /// <param name="id">The id of the index.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>The index.</returns>
+        public async Task<SignalEntity> FindAsync(string id, CancellationToken cancellationToken = default)
+        {
+            if (id == null) throw new ArgumentNullException(nameof(id));
+            return await GroupGetAsync<SignalEntity>("Item", new Dictionary<string, object> { { "id", id } }, cancellationToken).ConfigureAwait(false);
+        }
+
+
+        /// <summary>
+        /// Retrieve statistics on all indexes.
+        /// </summary>
+        /// <param name="cancellationToken"><see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>A list containing matching expression indexes.</returns>
+        public async Task<List<IndexEntity>> ListAsync(CancellationToken cancellationToken = default)
+        {
+            return await GroupListAsync<IndexEntity>("Items", cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+        
+        /// <summary>
+        /// Suppress an index. Not all index types can be suppressed: signal indexes do support suppression, in the case
+        /// of which the <see cref="SignalEntity.IsIndexSuppressed"/> flag will be set to <c langword="false"/>.
+        /// Expression indexes can only be suppressed by deleting the associated <see cref="ExpressionIndexEntity"/>
+        /// and alert indexes can only be suppressed by deleting the corresponding <see cref="AlertEntity"/>.
+        /// </summary>
+        /// <param name="entity">The index to suppress.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> allowing the operation to be canceled.</param>
+        /// <returns>A task indicating completion.</returns>
+        public async Task SuppressAsync(IndexEntity entity, CancellationToken cancellationToken = default)
+        {
+            await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

src/Seq.Api/ResourceGroups/SignalsResourceGroup.cs

@@ -78,6 +78,7 @@ public async Task<SignalEntity> AddAsync(SignalEntity entity, CancellationToken
         {
             return await GroupCreateAsync<SignalEntity, SignalEntity>(entity, cancellationToken: cancellationToken).ConfigureAwait(false);
         }
+        
         /// <summary>
         /// Remove an existing signal.
         /// </summary>

src/Seq.Api/Seq.Api.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <Description>Client library for the Seq HTTP API.</Description>
-    <VersionPrefix>2024.2.0</VersionPrefix>
+    <VersionPrefix>2024.3.0</VersionPrefix>
     <Authors>Datalust;Contributors</Authors>
     <TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

src/Seq.Api/SeqConnection.cs

@@ -149,12 +149,22 @@ public void Dispose()
         /// Perform operations on queries and filter expressions.
         /// </summary>
         public ExpressionsResourceGroup Expressions => new ExpressionsResourceGroup(this);
+        
+        /// <summary>
+        /// Perform operations on expression indexes.
+        /// </summary>
+        public ExpressionIndexesResourceGroup ExpressionIndexes => new ExpressionIndexesResourceGroup(this);
 
         /// <summary>
         /// Perform operations on NuGet feeds.
         /// </summary>
         public FeedsResourceGroup Feeds => new FeedsResourceGroup(this);
 
+        /// <summary>
+        /// Statistics about indexes.
+        /// </summary>
+        public IndexesResourceGroup Indexes => new IndexesResourceGroup(this);
+
         /// <summary>
         /// Perform operations on the Seq license certificate.
         /// </summary>