Release: AWS secrets adapters, crypto VFS vault, docs overhaul, and audit hardening

SquidStd.slnx

@@ -37,6 +37,10 @@
         <Project Path="src/SquidStd.Mail.Abstractions/SquidStd.Mail.Abstractions.csproj" />
         <Project Path="src/SquidStd.Mail.MailKit/SquidStd.Mail.MailKit.csproj" />
         <Project Path="src/SquidStd.Mail.Queue/SquidStd.Mail.Queue.csproj" />
+        <Project Path="src/SquidStd.Crypto/SquidStd.Crypto.csproj" />
+        <Project Path="src/SquidStd.Vfs.Abstractions/SquidStd.Vfs.Abstractions.csproj" />
+        <Project Path="src/SquidStd.Vfs/SquidStd.Vfs.csproj" />
+        <Project Path="src/SquidStd.Secrets.Aws/SquidStd.Secrets.Aws.csproj" />
     </Folder>
     <Folder Name="/samples/">
         <Project Path="samples/SquidStd.Samples.WorkerSystem/SquidStd.Samples.WorkerSystem.csproj" />
@@ -55,6 +59,10 @@
         <Project Path="samples/SquidStd.Samples.Caching/SquidStd.Samples.Caching.csproj" />
         <Project Path="samples/SquidStd.Samples.EventsJobsScheduling/SquidStd.Samples.EventsJobsScheduling.csproj" />
         <Project Path="samples/SquidStd.Samples.GettingStarted/SquidStd.Samples.GettingStarted.csproj" />
+        <Project Path="samples/SquidStd.Samples.Crypto/SquidStd.Samples.Crypto.csproj" />
+        <Project Path="samples/SquidStd.Samples.Vfs/SquidStd.Samples.Vfs.csproj" />
+        <Project Path="samples/SquidStd.Samples.Secrets/SquidStd.Samples.Secrets.csproj" />
+        <Project Path="samples/SquidStd.Samples.Actors/SquidStd.Samples.Actors.csproj" />
     </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />

docs/articles/actors.md

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

docs/articles/concepts/abstractions-first.md

@@ -0,0 +1,21 @@
+# Abstractions first
+
+SquidStd is built abstractions-first: code depends on contracts, and concrete backends are chosen at composition time. This is what makes a SquidStd application easy to test and easy to retarget.
+
+## Contract package plus provider packages
+
+Each capability is a contract package paired with one or more provider packages. The contract package — `*.Abstractions` — defines the interfaces and DTOs. Provider packages implement them. Your application references the abstraction and depends on the provider only in the host project. See the [architecture](architecture.md) overview for how this shapes the package graph.
+
+## In-memory for tests, external for prod
+
+Most capabilities ship an in-memory provider for tests and an external-backend provider for production:
+
+- **Messaging** — in-memory, or `SquidStd.Messaging.RabbitMq` / `SquidStd.Messaging.Sqs`.
+- **Caching** — in-memory, or `SquidStd.Caching.Redis`.
+- **Storage** — file-backed, or `SquidStd.Storage.S3` (S3 and MinIO).
+
+Tests run fast and deterministically against the in-memory provider; production swaps in the external backend.
+
+## Swapping providers without touching call sites
+
+Because call sites depend only on the contract, switching backends is a registration change in the host — `container.AddInMemoryMessaging()` versus `container.AddRabbitMqMessaging(...)` — with no edits to the code that publishes or consumes messages. See [dependency injection](dependency-injection.md) for the registration pattern that makes the swap a one-line change.

docs/articles/concepts/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+SquidStd is a modular .NET toolkit. Rather than a single monolithic library, it ships one package per capability, so an application depends only on the pieces it actually uses.
+
+## Modular by design
+
+Every capability is split in two: an `*.Abstractions` package that holds the contracts (interfaces and DTOs) and one or more provider packages that implement them. For example `SquidStd.Messaging.Abstractions` defines the messaging contracts, while `SquidStd.Messaging`, `SquidStd.Messaging.RabbitMq`, and `SquidStd.Messaging.Sqs` provide implementations. This keeps call sites coupled to contracts, not to a concrete backend. See [abstractions first](abstractions-first.md) for why this matters.
+
+## Layers
+
+The dependency flow runs in one direction:
+
+- **Core** (`SquidStd.Core`) — primitives, options, and the building blocks everything else sits on.
+- **Abstractions** — per-capability contract packages.
+- **Providers** — concrete implementations of those contracts.
+- **Host** — `SquidStdBootstrap` composes services and runs them.
+
+Higher layers depend on lower ones, never the reverse.
+
+## Package graph
+
+```mermaid
+graph TD
+  Core[SquidStd.Core] --> Services[SquidStd.Services.Core]
+  Abstr[*.Abstractions contracts] --> Providers[Provider packages]
+  Services --> Host[SquidStdBootstrap host]
+  Providers --> Host
+  Host --> App[Your application]
+```
+
+## Next
+
+- [Bootstrap lifecycle](bootstrap-lifecycle.md) — how the host starts and stops services.
+- [Abstractions first](abstractions-first.md) — the contract-plus-provider pattern in depth.

docs/articles/concepts/bootstrap-lifecycle.md

@@ -0,0 +1,51 @@
+# Bootstrap lifecycle
+
+`SquidStdBootstrap` is the entry point that wires up dependency injection and drives the lifecycle of every registered service. The flow is always the same: create, configure, start, stop.
+
+## Create
+
+Begin by creating the bootstrap from `SquidStdOptions`:
+
+```csharp
+var bootstrap = SquidStdBootstrap.Create(new SquidStdOptions
+{
+    ConfigName = "squidstd",
+    RootDirectory = AppContext.BaseDirectory
+});
+```
+
+`ConfigName` selects the configuration file and `RootDirectory` anchors relative paths.
+
+## ConfigureServices
+
+Register your services into the DryIoc container:
+
+```csharp
+bootstrap.ConfigureServices(container =>
+{
+    container.AddSomething();
+});
+```
+
+See [dependency injection](dependency-injection.md) for the container and the `AddXxx` / `RegisterXxx` pattern.
+
+## Start and stop over ISquidStdService
+
+Services implementing `ISquidStdService` participate in the lifecycle. On `StartAsync` they are started in registration order; on `StopAsync` they are stopped in reverse order, so dependencies remain available while their dependents shut down.
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Bootstrap as SquidStdBootstrap
+  participant Svc as ISquidStdService(s)
+  App->>Bootstrap: Create(options)
+  App->>Bootstrap: ConfigureServices(container)
+  App->>Bootstrap: StartAsync()
+  Bootstrap->>Svc: StartAsync() (in order)
+  App->>Bootstrap: StopAsync()
+  Bootstrap->>Svc: StopAsync() (reverse order)
+```
+
+## RunAsync for long-running hosts
+
+For long-running hosts, call `RunAsync`. It starts every service and then blocks until cancellation, stopping services cleanly on shutdown. Resolve dependencies anywhere with `bootstrap.Resolve<T>()`. See the [architecture](architecture.md) overview for how the host fits the layers.

docs/articles/concepts/dependency-injection.md

@@ -0,0 +1,32 @@
+# Dependency injection
+
+SquidStd resolves every service through dependency injection. Understanding the container and its registration pattern is the key to wiring an application together.
+
+## DryIoc container
+
+The DI container is [DryIoc](https://github.com/dadhi/DryIoc), exposed as `IContainer`. It is fast, supports rich lifetimes, and validates required services at resolution time. Because the container owns validation, constructor dependencies that arrive from DI do not need manual null guards.
+
+## The AddXxx / RegisterXxx extension pattern
+
+Modules register themselves through C# 14 `extension(IContainer)` members named `AddXxx(...)` or `RegisterXxx(...)`. Each capability ships its own registration entry point, so wiring a module is a single call:
+
+```csharp
+container.AddInMemoryMessaging();
+container.RegisterCoreServices();
+```
+
+This keeps registration discoverable and colocated with the package that owns it.
+
+## Resolving through the bootstrap
+
+Once configured, resolve services through the bootstrap:
+
+```csharp
+var bus = bootstrap.Resolve<IEventBus>();
+```
+
+In most code you let constructor injection do the work and never call `Resolve` directly. See [bootstrap lifecycle](bootstrap-lifecycle.md) for where `ConfigureServices` runs.
+
+## Singletons and lifecycle
+
+Most infrastructure services are registered as singletons and live for the life of the host. Services implementing `ISquidStdService` are additionally started and stopped by the bootstrap, so a singleton can hold long-lived resources that are released on shutdown.

docs/articles/concepts/messaging-models.md

@@ -0,0 +1,27 @@
+# Messaging models
+
+SquidStd offers three in-process messaging models. Each fits a different shape of communication, and they can be mixed freely within one application.
+
+## Event Bus
+
+The Event Bus (`IEventBus`) is a stateless broadcast. Publishers call `PublishAsync` and any number of subscribers registered with `Subscribe` receive the event. Senders do not know who listens, and there is no return value. Use it for fan-out notifications where many parts of the system react to something that happened.
+
+## Command Dispatcher
+
+The Command Dispatcher is a stateless request routed to a single handler that returns a result. Unlike the Event Bus there is exactly one handler per command, and the caller awaits its result. Use it for request/response work — validating input, performing an operation, returning an outcome — where ownership of the action is unambiguous.
+
+## Actors
+
+Actors (`Actor<TMessage>`) provide an ordered, stateful, per-entity mailbox. Each actor processes its messages one at a time in order, so state inside an actor needs no locks. Send fire-and-forget messages with `TellAsync` or request a reply with `AskAsync`. Use actors when you need serialized access to per-entity state, such as a single account, device, or session.
+
+## Choosing
+
+```mermaid
+flowchart TD
+  Q{Need ordered, per-entity state?} -->|yes| A[Actors]
+  Q -->|no| R{Request → single handler with a result?}
+  R -->|yes| C[Command Dispatcher]
+  R -->|no| E[Event Bus broadcast]
+```
+
+All three are contract-first; see [abstractions first](abstractions-first.md) for swapping in external transports.

docs/articles/crypto.md

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

docs/articles/getting-started.md

@@ -7,14 +7,19 @@ dotnet add package SquidStd.Services.Core
 ```
 
 ```csharp
-using DryIoc;
-using SquidStd.Services.Core.Extensions;
+using SquidStd.Core.Data.Bootstrap;
+using SquidStd.Services.Core.Services.Bootstrap;
 
-var container = new Container();
+// Core services wired automatically: config manager, event bus, command dispatcher,
+// job system, timer/cron scheduler, metrics, health checks, storage and secrets.
+var bootstrap = SquidStdBootstrap.Create(
+    new SquidStdOptions { ConfigName = "squidstd", RootDirectory = AppContext.BaseDirectory });
 
-// config manager + event bus + jobs + timer wheel + dispatcher + metrics + storage + secrets
-container.RegisterCoreServices("squidstd", Directory.GetCurrentDirectory());
+await bootstrap.StartAsync();
+// … resolve services, opt into modules with bootstrap.ConfigureServices(…) …
+await bootstrap.StopAsync();
 ```
 
-From here, add focused packages as needed — see the per-package guides in the sidebar and the
-[API reference](../api/index.md).
+Opt into modules with `ConfigureServices`, e.g. `container.AddInMemoryCache()`. See the
+[Concepts](concepts/bootstrap-lifecycle.md) for the full lifecycle and
+[Packages](getting-started.md) for per-module reference.

docs/articles/guides/choosing-caching.md

@@ -0,0 +1,19 @@
+# Choosing a cache
+
+The caching abstraction (`ICacheService`) has two backends. Both expose the same
+API, so you can develop against in-memory and promote to Redis without code changes.
+
+| Backend | Package · entrypoint | Use case | Scope | Survives restart | Ops cost |
+|---|---|---|---|---|---|
+| In-memory | `SquidStd.Caching` · `AddInMemoryCache` | Tests, single instance | Per-process | No | None |
+| Redis | `SquidStd.Caching.Redis` · `AddRedisCache` | Multiple instances, shared cache | Distributed | Yes (with persistence) | Run/host Redis |
+
+```csharp
+bootstrap.ConfigureServices(container => container.AddRedisCache("localhost:6379"));
+```
+
+## Recommendation
+
+Use `AddInMemoryCache` for tests and single-instance deployments; switch to
+`AddRedisCache` as soon as you run more than one instance or need the cache to
+outlive the process.

docs/articles/guides/choosing-messaging.md

@@ -0,0 +1,19 @@
+# Choosing a messaging backend
+
+SquidStd exposes one messaging abstraction with three interchangeable backends.
+Pick by where you run and what delivery guarantees you need.
+
+| Backend | Package · entrypoint | Use case | Ordering | Durability | Ops cost |
+|---|---|---|---|---|---|
+| In-memory | `SquidStd.Messaging` · `AddInMemoryMessaging` | Tests, single-process apps | Per-process | None (lost on restart) | None |
+| RabbitMQ | `SquidStd.Messaging.RabbitMq` · `AddRabbitMqMessaging` | Self-hosted services, work queues | Per-queue | Durable queues | Run a broker |
+| SQS/SNS | `SquidStd.Messaging.Sqs` · `AddSqsMessaging` | AWS-native, serverless | FIFO queues only | Managed, durable | Managed (AWS) |
+
+```csharp
+bootstrap.ConfigureServices(container => container.AddRabbitMqMessaging("amqp://localhost"));
+```
+
+## Recommendation
+
+Use `AddInMemoryMessaging` for tests and single-process apps, `AddRabbitMqMessaging`
+when you self-host, and `AddSqsMessaging` when you are already on AWS.

docs/articles/guides/choosing-search-database.md

@@ -0,0 +1,23 @@
+# Choosing search & database
+
+Full-text search and relational persistence are different tools. Use the search
+provider for queries over text and documents, and the database module (backed by
+FreeSql) for structured, relational data.
+
+| Need | Module · entrypoint | Provider(s) | Use case |
+|---|---|---|---|
+| Full-text / document search | `SquidStd.Search.Elasticsearch` · `AddElasticsearch` | Elasticsearch | Relevance ranking, faceting, log/document search |
+| Relational data | `SquidStd.Database` · `RegisterDatabase` | FreeSql: Sqlite, PostgreSQL, MySql, SqlServer | Transactional records, joins, constraints |
+
+The database provider is selected via `DatabaseProviderType` (`Sqlite`,
+`PostgreSQL`, `MySql`, `SqlServer`) in the `database` config section.
+
+```csharp
+bootstrap.ConfigureServices(container => container.RegisterDatabase());
+```
+
+## Recommendation
+
+Reach for `AddElasticsearch` when the core requirement is searching text or
+documents by relevance; use `RegisterDatabase` with the FreeSql provider that
+matches your engine for everything relational. They compose — many apps use both.

docs/articles/guides/choosing-storage.md

@@ -0,0 +1,23 @@
+# Choosing a storage backend
+
+The storage abstraction (`IStorageService`) stores blobs by key. There are two
+providers; the S3 provider also targets any S3-compatible server such as MinIO.
+
+| Backend | Package · entrypoint | Use case | Shared across hosts | Ops cost |
+|---|---|---|---|---|
+| Local file | `SquidStd.Storage` · `AddFileStorage` | Dev, single host, simple persistence | No | None |
+| S3 | `SquidStd.Storage.S3` · `AddS3Storage` | AWS-native object storage | Yes | Managed (AWS) |
+| MinIO | `SquidStd.Storage.S3` · `AddS3Storage` (set `ServiceUrl`) | Self-hosted S3-compatible storage | Yes | Run MinIO |
+
+```csharp
+bootstrap.ConfigureServices(container => container.AddS3Storage(new S3StorageOptions
+{
+    // ServiceUrl points at AWS S3 or a self-hosted MinIO endpoint
+}));
+```
+
+## Recommendation
+
+Use `AddFileStorage` for development and single-host apps. Use `AddS3Storage`
+against AWS S3 in the cloud, or against a MinIO endpoint (via `ServiceUrl`) when
+you need S3 semantics on self-hosted infrastructure.

docs/articles/guides/configuration.md

@@ -0,0 +1,45 @@
+# Configuration
+
+SquidStd loads configuration from a single YAML file. Each module registers a
+strongly-typed section; the config manager deserializes it, expands environment
+variables, and publishes the populated object into the container so you can
+resolve it like any other service.
+
+## Steps
+
+1. **Point the bootstrap at your config file.** `SquidStdOptions.ConfigName` is the
+   logical file name (default `squidstd`, so `squidstd.yaml`) and
+   `RootDirectory` is the directory it is searched in.
+2. **Register a section.** Call `RegisterConfigSection<TConfig>` with the section
+   name (the top-level YAML key). Provide a `createDefault` factory so the file
+   is generated with sensible defaults on first run.
+3. **Use environment variables.** Any `string` property whose value contains a
+   `$VAR` token is expanded from the environment when the section is loaded.
+   Unknown tokens are left untouched.
+4. **Read values.** Resolve the config type from the container wherever you need it.
+
+```csharp
+public sealed class MyServiceConfig
+{
+    public string Endpoint { get; set; } = string.Empty; // e.g. "https://$API_HOST"
+    public int Retries { get; set; } = 3;
+}
+
+var bootstrap = SquidStdBootstrap.Create(
+    new SquidStdOptions { ConfigName = "squidstd", RootDirectory = AppContext.BaseDirectory });
+
+bootstrap.ConfigureServices(container =>
+    container.RegisterConfigSection("myService", static () => new MyServiceConfig()));
+
+await bootstrap.StartAsync();
+
+var config = container.Resolve<MyServiceConfig>();
+```
+
+The corresponding `squidstd.yaml`:
+
+```yaml
+myService:
+  endpoint: "https://$API_HOST"
+  retries: 5
+```

docs/articles/guides/observability.md

@@ -0,0 +1,35 @@
+# Observability
+
+`SquidStd.Telemetry.OpenTelemetry` wires OpenTelemetry tracing and metrics into
+the bootstrap as a managed service. Spans flow from SquidStd's own
+`ActivitySource` instances and from anything else in your process.
+
+## Steps
+
+1. **Add the package** `SquidStd.Telemetry.OpenTelemetry`.
+2. **Register telemetry** with `AddSquidStdTelemetry`, passing a `TelemetryOptions`
+   with your `ServiceName`.
+3. **Choose an exporter.** Set `OtlpEndpoint` / `OtlpProtocol` to ship to a
+   collector (the default endpoint is `http://localhost:4317`, gRPC). For local
+   debugging set `EnableConsoleExporter = true` to also print spans to stdout.
+4. **Tune sampling** with `TracingSampleRatio` (0..1) and toggle pipelines with
+   `EnableTracing` / `EnableMetrics`.
+
+```csharp
+bootstrap.ConfigureServices(container =>
+    container.AddSquidStdTelemetry(new TelemetryOptions
+    {
+        ServiceName = "orders-worker",
+        OtlpEndpoint = "http://otel-collector:4317",
+        OtlpProtocol = OtlpProtocolType.Grpc,
+        EnableConsoleExporter = false,
+        TracingSampleRatio = 1.0
+    }));
+```
+
+## ActivitySource convention
+
+SquidStd modules name their `ActivitySource` instances with the `SquidStd.*`
+prefix (for example `SquidStd.Messaging`). Subscribe to that prefix in your
+collector or tracer-provider configuration to capture all framework spans, and
+follow the same convention for your own application sources.