Release: caching, scheduling, database, messaging, packaging & docs

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: "nuget"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "build"
+      include: "scope"
+    groups:
+      dotnet:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    groups:
+      actions:
+        patterns:
+          - "*"

.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ develop ]
+  pull_request:
+    branches: [ develop ]
+  schedule:
+    - cron: "27 3 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: codeql-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (C#)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: csharp
+          build-mode: none
+          queries: security-and-quality
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:csharp"

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Install DocFX
+        run: dotnet tool update -g docfx
+
+      - name: Build site
+        run: docfx docs/docfx.json
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.github/workflows/nuget-publish.yml

@@ -47,13 +47,11 @@ jobs:
       - name: Pack publishable packages
         run: |
           set -euo pipefail
-          packages=(
-            "src/SquidStd.Abstractions/SquidStd.Abstractions.csproj"
-            "src/SquidStd.Core/SquidStd.Core.csproj"
-            "src/SquidStd.Network/SquidStd.Network.csproj"
-            "src/SquidStd.Plugin.Abstractions/SquidStd.Plugin.Abstractions.csproj"
-            "src/SquidStd.Services.Core/SquidStd.Services.Core.csproj"
-          )
+          # Discover every project opted-in with <PublishNuget>true</PublishNuget>.
+          mapfile -t packages < <(grep -ril --include='*.csproj' '<PublishNuget>true</PublishNuget>' src | sort)
+          if [[ ${#packages[@]} -eq 0 ]]; then
+            echo "No project has <PublishNuget>true</PublishNuget>"; exit 1
+          fi
           for project in "${packages[@]}"; do
             echo "Packing ${project}"
             dotnet pack "${project}" -c Release --no-build

.gitignore

@@ -589,3 +589,6 @@ definitions.lua
 
 dist/
 benchmarks/.compare
+
+# CodeGraph local index
+.codegraph/

CODE_CONVENTION.md

@@ -99,7 +99,7 @@ public enum DirectoryType { Scripts, Logs, Plugins, Configs }
 
 ## 7. Strings
 
-- Always use `""` instead of `string.Empty`.
+- Always use `string.Empty` instead of `""`.
 
 ## 8. Logging
 
@@ -201,7 +201,7 @@ tests/SquidStd.Tests/Support/FakeSourcePlugin.cs    → namespace SquidStd.Tests
 - No TODO comments without a tracked follow-up.
 - No inconsistent naming across domains.
 - Keep warnings under control; do not normalize noisy warnings.
-- No `string.Empty` — use `""`.
+- No literal `""` — use `string.Empty`.
 - No primary constructors.
 - No expression-bodied constructors.
 

Directory.Build.props

@@ -72,4 +72,12 @@
         <None Include="$(MSBuildThisFileDirectory)assets/icon.png" Pack="true" PackagePath="" Visible="false" />
     </ItemGroup>
 
+    <!-- Package Readme (opt-in per project that ships a README.md) -->
+    <PropertyGroup Condition="Exists('$(MSBuildProjectDirectory)/README.md')">
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+    </PropertyGroup>
+    <ItemGroup Condition="Exists('$(MSBuildProjectDirectory)/README.md')">
+        <None Include="README.md" Pack="true" PackagePath="\" Visible="false" />
+    </ItemGroup>
+
 </Project>

README.md

@@ -1,10 +1,11 @@
 <p align="center">
-  <img src="assets/icon.png" alt="SquidStd" width="128" height="128" />
+  <img src="assets/icon.png" alt="squid-std" width="128" height="128" />
 </p>
 
-<h1 align="center">SquidStd</h1>
+<h1 align="center">squid-std</h1>
 
 <p align="center">
+  <img src="https://img.shields.io/badge/.NET-10.0-512BD4.svg" alt=".NET 10" />
   <a href="https://github.com/tgiachi/SquidStd/actions/workflows/ci.yml"><img src="https://github.com/tgiachi/SquidStd/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/tgiachi/SquidStd/gh-pages/badges/tests.json" alt="tests" />
   <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/tgiachi/SquidStd/gh-pages/badges/coverage.json" alt="coverage" />
@@ -13,17 +14,96 @@
 
 ## Overview
 
-Short description goes here.
+**squid-std** is a batteries-included standard library for .NET, distilled from years and years
+of building real-world server software. Instead of re-solving the same problems on every project,
+it bundles the foundations you reach for again and again behind small, well-defined contracts:
+
+- **Security & hashing** — password hashing and verification (`HashUtils`), AES-GCM secret
+  protection and a pluggable secret store (`ISecretProtector` / `ISecretStore`).
+- **Configuration** — a YAML-backed config manager with section registration and environment-variable expansion.
+- **Serialization** — unified JSON/YAML utilities (`JsonUtils`, `YamlUtils`) and a shared `IDataSerializer` / `IDataDeserializer`.
+- **String & platform helpers** — case converters (camel/kebab/snake/pascal/…), network, version, platform and resource utilities.
+- **Runtime services** — DI bootstrap, event bus, job system, timer/cron scheduler, metrics and storage.
+- **Infrastructure modules** — messaging (in-memory + RabbitMQ), caching (in-memory + Redis),
+  database access, networking (TCP/UDP) and Lua scripting.
+
+Everything is modular: take only the packages you need, each behind a clean abstraction with an
+in-memory implementation for tests and an external backend for production.
+
+## Requirements
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download)
+- [Docker](https://www.docker.com/) — only for running the integration tests (Testcontainers spin up RabbitMQ and Redis).
+
+## Quick Start
+
+```bash
+dotnet add package SquidStd.Services.Core
+dotnet add package SquidStd.Caching
+```
+
+```csharp
+using SquidStd.Caching.Abstractions.Interfaces;
+using SquidStd.Caching.Extensions;
+using SquidStd.Services.Core.Services.Bootstrap;
+
+// Create the bootstrapper (registers the core services), then opt into the modules you need.
+var bootstrap = SquidStdBootstrap.Create()
+    .ConfigureServices(container => container.AddInMemoryCache());
+
+await bootstrap.StartAsync();
+
+var cache = bootstrap.Resolve<ICacheService>();
+await cache.SetAsync("answer", 42, TimeSpan.FromMinutes(5));
+var answer = await cache.GetAsync<int>("answer");
+
+await bootstrap.StopAsync();
+```
+
+`SquidStdBootstrap` owns a DryIoc container, wires the core services, and drives the
+`StartAsync` / `StopAsync` lifecycle of every registered `ISquidStdService`. Use `RunAsync` to
+block until cancellation for long-running hosts.
 
 ## Packages
 
-| Package | Version | Downloads |
-|---------|---------|-----------|
-| `SquidStd.Abstractions` | [![NuGet](https://img.shields.io/nuget/v/SquidStd.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Abstractions/) | ![Downloads](https://img.shields.io/nuget/dt/SquidStd.Abstractions.svg) |
-| `SquidStd.Core` | [![NuGet](https://img.shields.io/nuget/v/SquidStd.Core.svg)](https://www.nuget.org/packages/SquidStd.Core/) | ![Downloads](https://img.shields.io/nuget/dt/SquidStd.Core.svg) |
-| `SquidStd.Network` | [![NuGet](https://img.shields.io/nuget/v/SquidStd.Network.svg)](https://www.nuget.org/packages/SquidStd.Network/) | ![Downloads](https://img.shields.io/nuget/dt/SquidStd.Network.svg) |
-| `SquidStd.Plugin.Abstractions` | [![NuGet](https://img.shields.io/nuget/v/SquidStd.Plugin.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Plugin.Abstractions/) | ![Downloads](https://img.shields.io/nuget/dt/SquidStd.Plugin.Abstractions.svg) |
-| `SquidStd.Services.Core` | [![NuGet](https://img.shields.io/nuget/v/SquidStd.Services.Core.svg)](https://www.nuget.org/packages/SquidStd.Services.Core/) | ![Downloads](https://img.shields.io/nuget/dt/SquidStd.Services.Core.svg) |
+| Package | Description | Links |
+|---------|-------------|-------|
+| `SquidStd.Core` | Foundational contracts & utilities (config, event bus, jobs, metrics, storage, YAML/JSON, Serilog sink). | [readme](src/SquidStd.Core/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Core.svg)](https://www.nuget.org/packages/SquidStd.Core/) |
+| `SquidStd.Abstractions` | DI registration plumbing (`ISquidStdService`, `RegisterStdService`, `RegisterConfigSection`). | [readme](src/SquidStd.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Abstractions/) |
+| `SquidStd.Services.Core` | Concrete services: config, event bus, jobs, timer/cron scheduler, dispatcher, metrics, storage. | [readme](src/SquidStd.Services.Core/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Services.Core.svg)](https://www.nuget.org/packages/SquidStd.Services.Core/) |
+| `SquidStd.AspNetCore` | ASP.NET Core host integration for the SquidStd service stack. | [readme](src/SquidStd.AspNetCore/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.AspNetCore.svg)](https://www.nuget.org/packages/SquidStd.AspNetCore/) |
+| `SquidStd.Network` | TCP/UDP servers & clients, sessions, framing/middleware pipeline, span readers/writers. | [readme](src/SquidStd.Network/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Network.svg)](https://www.nuget.org/packages/SquidStd.Network/) |
+| `SquidStd.Plugin.Abstractions` | Plugin contracts (`ISquidStdPlugin`, metadata, context). | [readme](src/SquidStd.Plugin.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Plugin.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Plugin.Abstractions/) |
+| `SquidStd.Database.Abstractions` | Provider-agnostic data-access contracts (`IDataAccess<T>`, `BaseEntity`, `PagedResultData`). | [readme](src/SquidStd.Database.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Database.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Database.Abstractions/) |
+| `SquidStd.Database` | FreeSql-backed data access (CRUD/bulk/paging, URI connection strings, ZLinq helpers). | [readme](src/SquidStd.Database/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Database.svg)](https://www.nuget.org/packages/SquidStd.Database/) |
+| `SquidStd.Messaging.Abstractions` | Messaging contracts (`IMessageQueue`, `IQueueProvider`, serializer/metrics, listeners). | [readme](src/SquidStd.Messaging.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Messaging.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Messaging.Abstractions/) |
+| `SquidStd.Messaging` | In-memory messaging transport (`AddInMemoryMessaging`). | [readme](src/SquidStd.Messaging/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Messaging.svg)](https://www.nuget.org/packages/SquidStd.Messaging/) |
+| `SquidStd.Messaging.RabbitMq` | RabbitMQ messaging transport (`AddRabbitMqMessaging`). | [readme](src/SquidStd.Messaging.RabbitMq/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Messaging.RabbitMq.svg)](https://www.nuget.org/packages/SquidStd.Messaging.RabbitMq/) |
+| `SquidStd.Caching.Abstractions` | Caching contracts (`ICacheService`, `ICacheProvider`, `CacheService` facade, metrics, connection string). | [readme](src/SquidStd.Caching.Abstractions/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Caching.Abstractions.svg)](https://www.nuget.org/packages/SquidStd.Caching.Abstractions/) |
+| `SquidStd.Caching` | In-memory cache backend (`AddInMemoryCache`). | [readme](src/SquidStd.Caching/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Caching.svg)](https://www.nuget.org/packages/SquidStd.Caching/) |
+| `SquidStd.Caching.Redis` | Redis cache backend (`AddRedisCache`). | [readme](src/SquidStd.Caching.Redis/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Caching.Redis.svg)](https://www.nuget.org/packages/SquidStd.Caching.Redis/) |
+| `SquidStd.Scripting.Lua` | Lua scripting engine with attribute-based modules and event bridging. | [readme](src/SquidStd.Scripting.Lua/README.md) · [![NuGet](https://img.shields.io/nuget/v/SquidStd.Scripting.Lua.svg)](https://www.nuget.org/packages/SquidStd.Scripting.Lua/) |
+
+## Architecture
+
+squid-std follows a few consistent principles across every module:
+
+- **KISS** — small, focused types; one class / record / enum per file.
+- **Abstractions first** — each capability is split into an `*.Abstractions` package (interfaces,
+  DTOs, shared facade) plus one or more provider packages. Consumers depend on the abstraction.
+- **In-memory + external provider** — every infrastructure module ships an in-memory provider
+  (great for tests and local dev) and a production backend behind the same interface
+  (messaging: in-memory / RabbitMQ; caching: in-memory / Redis).
+- **DI-driven** — services are registered with DryIoc through `AddXxx(...)` extensions and resolved
+  through `SquidStdBootstrap`, which manages the `ISquidStdService` lifecycle.
+- **Convention over restructure** — interfaces under `Interfaces`, DTOs under `Data`, enums under
+  `Types`, internals under `Internal`. See [`CODE_CONVENTION.md`](CODE_CONVENTION.md).
+
+## Documentation
+
+Full API documentation is published with DocFX to GitHub Pages:
+**[tgiachi.github.io/SquidStd](https://tgiachi.github.io/SquidStd/)**. Each package also ships its
+own README (linked in the table above).
 
 ## Build
 
@@ -37,6 +117,23 @@ dotnet build SquidStd.slnx
 dotnet test SquidStd.slnx
 ```
 
+Integration tests (RabbitMQ, Redis) need Docker running; they use Testcontainers to start
+disposable containers automatically.
+
+## Contributing
+
+- Work happens on `develop`; `main` holds released code.
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for messages
+  (`feat:`, `fix:`, `refactor:`, `docs:`, `build:`, `test:`).
+- Follow the project conventions in [`CODE_CONVENTION.md`](CODE_CONVENTION.md).
+- Add tests for new behaviour and keep the suite green before opening a PR.
+
+## Versioning & Releases
+
+Releases are automated with [semantic-release](https://semantic-release.gitbook.io/): version
+numbers and the changelog are derived from the conventional-commit history, and the NuGet packages
+are published on release. Package versions follow [Semantic Versioning](https://semver.org/).
+
 ## License
 
 MIT - see [LICENSE](LICENSE).

SquidStd.slnx

@@ -1,8 +1,22 @@
 <Solution>
-    <Project Path="src/SquidStd.Abstractions/SquidStd.Abstractions.csproj" />
-    <Project Path="src/SquidStd.Core/SquidStd.Core.csproj" />
-    <Project Path="src/SquidStd.Network/SquidStd.Network.csproj" />
-    <Project Path="src/SquidStd.Plugin.Abstractions/SquidStd.Plugin.Abstractions.csproj" />
-    <Project Path="src/SquidStd.Services.Core/SquidStd.Services.Core.csproj" />
-    <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />
+    <Folder Name="/src/">
+        <Project Path="src/SquidStd.Abstractions/SquidStd.Abstractions.csproj" />
+        <Project Path="src/SquidStd.AspNetCore/SquidStd.AspNetCore.csproj" />
+        <Project Path="src/SquidStd.Caching.Abstractions/SquidStd.Caching.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Caching.Redis/SquidStd.Caching.Redis.csproj" />
+        <Project Path="src/SquidStd.Caching/SquidStd.Caching.csproj" />
+        <Project Path="src/SquidStd.Core/SquidStd.Core.csproj" />
+        <Project Path="src/SquidStd.Database.Abstractions/SquidStd.Database.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Database/SquidStd.Database.csproj" />
+        <Project Path="src/SquidStd.Messaging.Abstractions/SquidStd.Messaging.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Messaging.RabbitMq/SquidStd.Messaging.RabbitMq.csproj" />
+        <Project Path="src/SquidStd.Messaging/SquidStd.Messaging.csproj" />
+        <Project Path="src/SquidStd.Network/SquidStd.Network.csproj" />
+        <Project Path="src/SquidStd.Plugin.Abstractions/SquidStd.Plugin.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Scripting.Lua/SquidStd.Scripting.Lua.csproj" />
+        <Project Path="src/SquidStd.Services.Core/SquidStd.Services.Core.csproj" />
+    </Folder>
+    <Folder Name="/tests/">
+        <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />
+    </Folder>
 </Solution>

docs/.gitignore

@@ -0,0 +1,4 @@
+_site/
+api/*.yml
+api/.manifest
+obj/

docs/api/index.md

@@ -0,0 +1,5 @@
+# API Reference
+
+Auto-generated reference for all published SquidStd packages, grouped by namespace. Use the sidebar to
+browse types and members. Each package's purpose and a usage example are in its
+[article](../articles/getting-started.md).

docs/articles/abstractions.md

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

docs/articles/aspnetcore.md

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

docs/articles/caching-abstractions.md

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

docs/articles/caching-redis.md

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

docs/articles/caching.md

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

docs/articles/core.md

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

docs/articles/database-abstractions.md

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

docs/articles/database.md

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

docs/articles/getting-started.md

@@ -0,0 +1,20 @@
+# Getting Started
+
+Install the package(s) you need and bootstrap the core services.
+
+```bash
+dotnet add package SquidStd.Services.Core
+```
+
+```csharp
+using DryIoc;
+using SquidStd.Services.Core.Extensions;
+
+var container = new Container();
+
+// config manager + event bus + jobs + timer wheel + dispatcher + metrics + storage + secrets
+container.RegisterCoreServices("squidstd", Directory.GetCurrentDirectory());
+```
+
+From here, add focused packages as needed — see the per-package guides in the sidebar and the
+[API reference](../api/index.md).

docs/articles/messaging-abstractions.md

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

docs/articles/messaging-rabbitmq.md

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

docs/articles/messaging.md

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