squid-std

Overview

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
• Docker — only for running the integration tests (Testcontainers spin up RabbitMQ and Redis).

Quick Start

dotnet add package SquidStd.Services.Core
dotnet add package SquidStd.Caching

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	Description	Links
SquidStd.Core	Foundational contracts & utilities (config, event bus, jobs, metrics, serialization, YAML/JSON, Serilog sink).	·
SquidStd.Abstractions	DI registration plumbing (ISquidStdService, RegisterStdService, RegisterConfigSection).	·
SquidStd.Generators	Roslyn source generators for event listener, service, config, worker, and Lua registration helpers.	·
SquidStd.Services.Core	Concrete services: config, event bus, jobs, timer/cron scheduler, dispatcher, metrics, health checks, secrets.	·
SquidStd.AspNetCore	ASP.NET Core host integration for the SquidStd service stack.	·
SquidStd.Network	TCP/UDP servers & clients, sessions, framing/middleware pipeline, span readers/writers.	·
SquidStd.Persistence.Abstractions	Binary-persistence contracts (IEntityStore<T,TKey>, IPersistenceService, journal/snapshot/registry, PersistenceConfig).	·
SquidStd.Persistence	In-memory entity store with durable binary snapshot + journal (WAL); serializer-agnostic engine.	·
SquidStd.Persistence.MessagePack	MessagePack-backed binary IDataSerializer for SquidStd.Persistence (recommended default).	·
SquidStd.Plugin.Abstractions	Plugin contracts (ISquidStdPlugin, metadata, context).	·
SquidStd.Database.Abstractions	Provider-agnostic data-access contracts (IDataAccess<T>, BaseEntity, PagedResultData).	·
SquidStd.Database	FreeSql-backed data access (CRUD/bulk/paging, URI connection strings, ZLinq helpers).	·
SquidStd.Messaging.Abstractions	Messaging contracts (IMessageQueue, IQueueProvider, serializer/metrics, listeners).	·
SquidStd.Messaging	In-memory messaging transport (AddInMemoryMessaging).	·
SquidStd.Messaging.RabbitMq	RabbitMQ messaging transport (AddRabbitMqMessaging).	·
SquidStd.Messaging.Sqs	AWS SQS/SNS transport: IQueueProvider over SQS (redrive→DLQ) and ITopicProvider via SNS+SQS fan-out (AddSqsMessaging).	·
SquidStd.Aws.Abstractions	Shared AWS connection config (AwsConfigEntry: region, credentials, endpoint override) for AWS-SDK providers.	·
SquidStd.Telemetry.Abstractions	Shared telemetry config (TelemetryOptions, OTLP protocol, SquidStd.* ActivitySource convention).	·
SquidStd.Telemetry.OpenTelemetry	OpenTelemetry tracing + metrics export (OTLP/console), standard instrumentation, metrics-snapshot bridge (AddSquidStdTelemetry).	·
SquidStd.Caching.Abstractions	Caching contracts (ICacheService, ICacheProvider, CacheService facade, metrics, connection string).	·
SquidStd.Caching	In-memory cache backend (AddInMemoryCache).	·
SquidStd.Caching.Redis	Redis cache backend (AddRedisCache).	·
SquidStd.Storage.Abstractions	Storage contracts (IStorageService, IObjectStorageService, StorageConfig, ListKeysAsync).	·
SquidStd.Storage	Local file storage backend (AddFileStorage).	·
SquidStd.Storage.S3	S3/MinIO storage backend (AddS3Storage).	·
SquidStd.Scripting.Lua	Lua scripting engine with attribute-based modules and event bridging.	·
SquidStd.Templating	Scriban templating with a named-template registry and templates/*.tmpl auto-load (AddTemplating).	·
SquidStd.Workers.Abstractions	Worker/manager shared contracts (JobRequest, WorkerHeartbeat, WorkerInfo, WorkerChannels).	·
SquidStd.Workers	Worker runtime: consume jobs, dispatch to IJobHandlers, publish heartbeats (AddWorkers).	·
SquidStd.Workers.Manager	Job enqueue, heartbeat registry, offline sweep, opt-in ASP.NET endpoints (AddWorkerManager).	·
SquidStd.Templates	dotnet new templates for scaffolding SquidStd projects (host, ASP.NET, worker, manager).	·
SquidStd.Search.Abstractions	Search/indexing contracts (IIndexableEntity, [SearchIndex], ISearchService).	·
SquidStd.Search.Elasticsearch	Elasticsearch indexing + constrained LINQ query provider (AddElasticsearch).	·
SquidStd.Mail.Abstractions	Mail contracts (MailMessage, MailReceivedEvent, IMailReader, MailOptions).	·
SquidStd.Mail.MailKit	IMAP/POP3 mail poller that publishes MailReceivedEvent (AddMail).	·
SquidStd.Mail.Queue	Outbound mail send queue over the messaging queue (AddMailQueue, IMailQueue).	·

Related projects

• Felix Network — a standalone secure binary mesh-networking library for .NET (and a constrained C/ESP32 target): AES-256-GCM encrypted, optionally DEFLATE-compressed messages over ENet (reliable UDP) behind a portable frame, with an optional self-forming mesh layer and a pluggable transport (ITransport). Published as SquidStd.Felix, SquidStd.Felix.MemoryPack, SquidStd.Felix.Mesh and SquidStd.Felix.Transport.Serial on NuGet. See the Felix Network guide for an overview.

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.

Documentation

Full API documentation is published with DocFX to GitHub Pages: tgiachi.github.io/squid-std. Each package also ships its own README (linked in the table above).

Build

dotnet build SquidStd.slnx

Test

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 for messages (feat:, fix:, refactor:, docs:, build:, test:).
• Follow the project conventions in 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: 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.

License

MIT - see LICENSE.