squid-std

Contents

• Overview
• Requirements
• Quick Start
• Project templates
• Packages
• Related projects
• Architecture
• Documentation
• Build
• Test
• Contributing
• Versioning & Releases
• Built on
• License

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 & crypto — password hashing (HashUtils), AES-GCM secret protection and a pluggable secret store (ISecretProtector / ISecretStore), an OpenPGP keyring (SquidStd.Crypto), and AWS KMS / Secrets Manager adapters.
• Configuration & serialization — a YAML-backed config manager with section registration and environment-variable expansion; unified JSON/YAML utilities and a shared IDataSerializer.
• Runtime services — DI bootstrap, event bus, command dispatcher, actors (ordered per-entity mailboxes), job system, timer/cron scheduler, metrics and health checks.
• Messaging & caching — in-memory, RabbitMQ and AWS SQS/SNS transports; in-memory and Redis caches.
• Data & storage — FreeSql data access, binary persistence (snapshot + WAL), local / S3 / MinIO object storage, and a virtual filesystem (physical / zip / in-memory + an encrypted vault, plus S3-compatible and database-backed backends and composable decorators).
• Search, mail & workers — Elasticsearch indexing with a constrained LINQ provider, IMAP/POP3 mail polling and an outbound mail queue, and a worker / manager runtime.
• Networking, scripting & observability — TCP/UDP servers with a framing/middleware pipeline, Lua scripting and Scriban templating, and OpenTelemetry tracing + metrics export.
• Terminal UI — MVVM for terminal apps via SquidStd.Tui: observable ViewModels, a fluent binder (+ AutoBind and a declarative DSL), ViewModel-first navigation, DryIoc wiring.

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 the integration tests (Testcontainers spin up RabbitMQ, Redis, Elasticsearch, MinIO and LocalStack on demand).

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.

A fuller example: event bus + a provider

using SquidStd.Core.Interfaces.Events;
using SquidStd.Caching.Abstractions.Interfaces;
using SquidStd.Caching.Extensions;
using SquidStd.Services.Core.Services.Bootstrap;

public sealed record OrderPlaced(string OrderId) : IEvent;

var bootstrap = SquidStdBootstrap.Create()
    .ConfigureServices(container => container.AddInMemoryCache());

await bootstrap.StartAsync();

var eventBus = bootstrap.Resolve<IEventBus>();   // core service, always available
var cache    = bootstrap.Resolve<ICacheService>();

// React to domain events…
using var subscription = eventBus.Subscribe<OrderPlaced>(async (e, ct) =>
    await cache.SetAsync($"order:{e.OrderId}", DateTimeOffset.UtcNow, TimeSpan.FromHours(1)));

// …and publish them.
await eventBus.PublishAsync(new OrderPlaced("A-1001"));

await bootstrap.StopAsync();

The event bus, config manager, job system, scheduler and metrics are wired by the bootstrapper out of the box; modules such as caching are opted in through ConfigureServices.

Project templates

Scaffold a ready-to-run project with the dotnet new template pack:

dotnet new install SquidStd.Templates

Template	Short name	What you get
Console host	squidstd-host	A SquidStdBootstrap console host.
ASP.NET minimal API	squidstd-aspnetcore	UseSquidStd + health checks + a sample endpoint + Dockerfile.
Worker microservice	squidstd-worker	AddWorkers + a sample IJobHandler + Dockerfile.
Worker manager	squidstd-manager	AddWorkerManager + MapWorkerManagerEndpoints + Dockerfile.

dotnet new squidstd-worker -n Acme.Resizer
dotnet new squidstd-manager -n Acme.Manager --messaging inmemory

--messaging (rabbitmq default | inmemory) is available on the worker and manager templates.

Packages

Core & hosting

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.Plugin.Abstractions	Plugin contracts (ISquidStdPlugin, metadata, context).	·

Networking

Package	Description	Links
SquidStd.Network	TCP/UDP servers & clients, sessions, framing/middleware pipeline, span readers/writers.	·

Messaging & actors

Package	Description	Links
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.Actors	Ordered, single-threaded, lock-free per-entity message processing on TPL Dataflow (Actor<T>, TellAsync/AskAsync).	·

Persistence & database

Package	Description	Links
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.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).	·

Caching

Package	Description	Links
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).	·

Storage & virtual filesystem

Package	Description	Links
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.Vfs.Abstractions	Virtual filesystem contracts (IVirtualFileSystem, ILockableFileSystem, VfsPath).	·
SquidStd.Vfs	Virtual filesystem providers — physical, in-memory, and zip — plus composable decorators (ReadOnlyFileSystem, ScopedFileSystem, OverlayFileSystem, CachingFileSystem) and VfsDirectories.	·
SquidStd.Vfs.S3	S3-compatible VFS backend — AWS S3, MinIO, Cloudflare R2, Backblaze B2 — via the MinIO SDK (RegisterS3FileSystem).	·
SquidStd.Vfs.Database	Database-backed VFS storing files as rows via SquidStd.Database / FreeSql (RegisterDatabaseFileSystem).	·

Security — crypto & secrets

Package	Description	Links
SquidStd.Crypto	OpenPGP key management/operations over an indexed keyring (SquidStd.Crypto.Pgp, RegisterPgp), password-based encryption (PasswordCipher, Argon2id + AES-256-GCM with a self-describing envelope), and the encrypted VFS vault decorator.	·
SquidStd.Secrets.Aws	AWS adapters for the secret seams — KMS envelope ISecretProtector and Secrets Manager ISecretStore.	·

Search

Package	Description	Links
SquidStd.Search.Abstractions	Search/indexing contracts (IIndexableEntity, [SearchIndex], ISearchService).	·
SquidStd.Search.Elasticsearch	Elasticsearch indexing + constrained LINQ query provider (AddElasticsearch).	·

Mail

Package	Description	Links
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).	·

Workers

Package	Description	Links
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).	·

User interface

Package	Description	Links
SquidStd.Tui	MVVM for terminal apps on Terminal.Gui v2 — observable ViewModels, a fluent binder (+ AutoBind and a declarative DSL), ViewModel-first navigation, DryIoc wiring.	·

Scripting & templating

Package	Description	Links
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).	·

Telemetry

Package	Description	Links
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).	·

Shared & tooling

Package	Description	Links
SquidStd.Aws.Abstractions	Shared AWS connection config (AwsConfigEntry: region, credentials, endpoint override) for AWS-SDK providers.	·
SquidStd.Templates	dotnet new templates for scaffolding SquidStd projects (host, ASP.NET, worker, manager).	·

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 need Docker running; Testcontainers starts disposable RabbitMQ, Redis, Elasticsearch, MinIO and LocalStack 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.

Built on

squid-std stands on a small set of well-established libraries:

• DI & logging — DryIoc, Serilog
• Data — FreeSql, MessagePack, YamlDotNet
• Messaging & cache — RabbitMQ.Client, StackExchange.Redis, AWS SDK for .NET
• Search, mail & storage — Elastic.Clients.Elasticsearch, MailKit, Minio
• Crypto — PgpCore over BouncyCastle
• Scripting & templating — MoonSharp (Lua), Scriban
• Observability — OpenTelemetry
• Scheduling — Cronos

License

MIT - see LICENSE.