merge: SquidStd.Search.Abstractions + SquidStd.Search.Elasticsearch (indexing + LINQ query)

Author: tgiachi

README.md

@@ -91,6 +91,8 @@ block until cancellation for long-running hosts.
 | `SquidStd.Workers` | Worker runtime: consume jobs, dispatch to `IJobHandler`s, publish heartbeats (`AddWorkers`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Workers/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Workers.svg)](https://www.nuget.org/packages/SquidStd.Workers/) |
 | `SquidStd.Workers.Manager` | Job enqueue, heartbeat registry, offline sweep, opt-in ASP.NET endpoints (`AddWorkerManager`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Workers.Manager/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Workers.Manager.svg)](https://www.nuget.org/packages/SquidStd.Workers.Manager/) |
 | `SquidStd.Templates` | `dotnet new` templates for scaffolding SquidStd projects (host, ASP.NET, worker, manager). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Templates/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Templates.svg)](https://www.nuget.org/packages/SquidStd.Templates/) |
+| `SquidStd.Search.Abstractions` | Search/indexing contracts (`IIndexableEntity`, `[SearchIndex]`, `ISearchService`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Search.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Search.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Search.Abstractions/) |
+| `SquidStd.Search.Elasticsearch` | Elasticsearch indexing + constrained LINQ query provider (`AddElasticsearch`). | [![readme](https://img.shields.io/badge/readme-1390A3.svg)](src/SquidStd.Search.Elasticsearch/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Search.Elasticsearch.svg)](https://www.nuget.org/packages/SquidStd.Search.Elasticsearch/) |
 
 ## Architecture
 

SquidStd.slnx

@@ -23,6 +23,8 @@
         <Project Path="src/SquidStd.Workers/SquidStd.Workers.csproj" />
         <Project Path="src/SquidStd.Workers.Manager/SquidStd.Workers.Manager.csproj" />
         <Project Path="src/SquidStd.Templates/SquidStd.Templates.csproj" />
+        <Project Path="src/SquidStd.Search.Abstractions/SquidStd.Search.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Search.Elasticsearch/SquidStd.Search.Elasticsearch.csproj" />
     </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />

docs/articles/search-abstractions.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Search.Abstractions/README.md)]

docs/articles/search-elasticsearch.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Search.Elasticsearch/README.md)]

docs/articles/toc.yml

@@ -46,6 +46,10 @@
   href: workers-manager.md
 - name: SquidStd.Templates
   href: templates.md
+- name: SquidStd.Search.Abstractions
+  href: search-abstractions.md
+- name: SquidStd.Search.Elasticsearch
+  href: search-elasticsearch.md
 - name: Serialization
   href: serialization.md
 - name: Scheduler

src/SquidStd.Search.Abstractions/Attributes/SearchIndexAttribute.cs

@@ -0,0 +1,18 @@
+namespace SquidStd.Search.Abstractions.Attributes;
+
+/// <summary>
+/// Declares the Elasticsearch index for a type. The name supports environment-variable expansion:
+/// <c>${VAR}</c> and <c>${VAR:-default}</c> (e.g. <c>"orders_${ENV:-dev}"</c>).
+/// </summary>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, Inherited = false)]
+public sealed class SearchIndexAttribute : Attribute
+{
+    /// <summary>The index name (template).</summary>
+    public string Name { get; }
+
+    /// <summary>Initializes the attribute with the index name template.</summary>
+    public SearchIndexAttribute(string name)
+    {
+        Name = name;
+    }
+}

src/SquidStd.Search.Abstractions/Exceptions/SearchException.cs

@@ -0,0 +1,17 @@
+namespace SquidStd.Search.Abstractions.Exceptions;
+
+/// <summary>Thrown when Elasticsearch returns a non-successful response.</summary>
+public sealed class SearchException : Exception
+{
+    /// <summary>Initializes the exception with a message.</summary>
+    public SearchException(string message)
+        : base(message)
+    {
+    }
+
+    /// <summary>Initializes the exception with a message and inner exception.</summary>
+    public SearchException(string message, Exception innerException)
+        : base(message, innerException)
+    {
+    }
+}

src/SquidStd.Search.Abstractions/Interfaces/IIndexableEntity.cs

@@ -0,0 +1,11 @@
+namespace SquidStd.Search.Abstractions.Interfaces;
+
+/// <summary>
+/// Marks an entity as indexable and supplies its document id. The target index comes from a
+/// <see cref="Attributes.SearchIndexAttribute" /> on the type (or the lowercased type name).
+/// </summary>
+public interface IIndexableEntity
+{
+    /// <summary>Stable document id within the index.</summary>
+    string IndexId { get; }
+}

src/SquidStd.Search.Abstractions/Interfaces/ISearchService.cs

@@ -0,0 +1,22 @@
+namespace SquidStd.Search.Abstractions.Interfaces;
+
+/// <summary>
+/// Indexes, deletes, and queries <see cref="IIndexableEntity" /> documents.
+/// </summary>
+public interface ISearchService
+{
+    /// <summary>Indexes (creates or replaces) a single document.</summary>
+    Task IndexAsync<T>(T entity, bool refresh = false, CancellationToken cancellationToken = default) where T : IIndexableEntity;
+
+    /// <summary>Indexes many documents in one bulk request.</summary>
+    Task IndexManyAsync<T>(IEnumerable<T> entities, bool refresh = false, CancellationToken cancellationToken = default) where T : IIndexableEntity;
+
+    /// <summary>Deletes a document by id. Returns <c>false</c> when it did not exist.</summary>
+    Task<bool> DeleteAsync<T>(string indexId, bool refresh = false, CancellationToken cancellationToken = default) where T : IIndexableEntity;
+
+    /// <summary>Creates the index for <typeparamref name="T" /> if it does not exist (dynamic mapping). Idempotent.</summary>
+    Task EnsureIndexAsync<T>(CancellationToken cancellationToken = default) where T : IIndexableEntity;
+
+    /// <summary>Returns a constrained <see cref="IQueryable{T}" /> translated to the Elasticsearch query DSL.</summary>
+    IQueryable<T> Query<T>() where T : IIndexableEntity;
+}

src/SquidStd.Search.Abstractions/README.md

@@ -0,0 +1,34 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tgiachi/squid-std/main/assets/icon.png" alt="SquidStd" width="120" height="120" />
+</p>
+
+<h1 align="center">SquidStd.Search.Abstractions</h1>
+
+<p align="center">
+  <a href="https://www.nuget.org/packages/SquidStd.Search.Abstractions/"><img src="https://img.shields.io/nuget/v/SquidStd.Search.Abstractions.svg" alt="NuGet" /></a>
+  <img src="https://img.shields.io/nuget/dt/SquidStd.Search.Abstractions.svg" alt="Downloads" />
+  <a href="https://tgiachi.github.io/squid-std/articles/search-abstractions.html"><img src="https://img.shields.io/badge/docs-DocFX-1390A3.svg" alt="docs" /></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" />
+</p>
+
+Search/indexing contracts for SquidStd: tag entities with `IIndexableEntity` + `[SearchIndex]` (with
+`${VAR}` / `${VAR:-default}` environment expansion) and query them via `ISearchService`.
+
+## Install
+
+```bash
+dotnet add package SquidStd.Search.Abstractions
+```
+
+## Key types
+
+| Type | Purpose |
+|------|---------|
+| `IIndexableEntity` | Marks an entity indexable and supplies its `IndexId`. |
+| `SearchIndexAttribute` | Declares the index name (env-expanded). |
+| `ISearchService` | Index / delete / ensure-index / `Query<T>()`. |
+| `SearchIndexNameResolver` | Resolves the index name from the attribute/type + environment. |
+
+## License
+
+MIT — part of [SquidStd](https://github.com/tgiachi/squid-std).