diff --git a/.gitignore b/.gitignore
index bc12bcb8..5c33783c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -801,4 +801,9 @@ src/.vscode/
/src/Sa.Media.FFmpeg/build/artifacts/
/src/Sa.Media.FFmpeg/build/build.*/
-*.lscache
\ No newline at end of file
+*.lscache
+
+# ai
+.qwen/
+.agents/
+/.github/skills
diff --git a/QWEN.md b/QWEN.md
new file mode 100644
index 00000000..b41f744b
--- /dev/null
+++ b/QWEN.md
@@ -0,0 +1,140 @@
+# Sa — .NET 10 Experimental AOT Library Suite
+
+## Project Overview
+
+**Sa** is a collection of reusable .NET 10 libraries focused on infrastructure patterns for distributed systems. It targets **.NET 10.0**, uses **Native AOT**, and follows the **Central Package Management (CPM)** pattern via `Directory.Packages.props`.
+
+### Libraries
+
+| Library | Purpose |
+|---|---|
+| **Sa** | Shared utility classes (LockRenewer, MurmurHash3, Retry, extensions) consumed by other libs via `` |
+| **Sa.Configuration** | Command-line argument parsing (`Arguments`) and secure secrets management from files/env vars/host key files |
+| **Sa.Configuration.PostgreSql** | PostgreSQL-backed dynamic configuration source — changes in DB reflect in-app without redeploy |
+| **Sa.Data.PostgreSql** | Lightweight Npgsql client wrapper |
+| **Sa.Data.S3** | S3 data client (Minio-compatible) |
+| **Sa.HybridFileStorage** | Hybrid file storage abstraction with automatic provider failover (FileSystem ↔ S3 ↔ Postgres) |
+| **Sa.HybridFileStorage.FileSystem** | FileSystem provider implementation |
+| **Sa.HybridFileStorage.S3** | S3 provider implementation |
+| **Sa.HybridFileStorage.Postgres** | PostgreSQL provider implementation |
+| **Sa.Media** | Async, memory-efficient WAV file reader (`AsyncWavReader`) |
+| **Sa.Media.FFmpeg** | FFmpeg .NET wrapper with built-in binaries (Win x64 / Linux), audio conversion, metadata extraction, channel split/join, DI support |
+| **Sa.Outbox** | Base Outbox pattern infrastructure for reliable message publishing |
+| **Sa.Outbox.PostgreSql** | PostgreSQL Outbox implementation — parallel processing, tenant support, scheduled data cleanup |
+| **Sa.Partitional.PostgreSql** | Declarative PostgreSQL table partitioning (time: day/month/year; list; range) with migration/deletion schedules |
+| **Sa.Schedule** | Scheduled task executor with failure strategies (close app, stop job, stop all jobs, ignore) |
+| **Sa.Utils.WorkQueue** | Async queue with concurrency limiting, built on `System.Threading.Channels` |
+
+### Samples
+
+Located in `src/Samples/`: Configuration.Web, FFMpeg.Console, HybridFileStorage.Console, Partitional.ConsoleApp, PgOutbox.ConsoleApp, Schedule.Console, Storage.Tests.
+
+### Tests
+
+Located in `src/Tests/`: 15 test projects using **xunit v3**, **Testcontainers** (PostgreSQL + Minio) for integration tests. Test fixtures in `src/Tests/Fixtures/`.
+
+---
+
+## Building and Running
+
+### Prerequisites
+
+- .NET 10 SDK
+- PowerShell (for local build scripts)
+
+### Build Commands
+
+```powershell
+# Full build (clean + restore + build)
+.\build\do_build.ps1
+
+# Run all tests
+.\build\do_test.ps1
+
+# Package NuGet packages (produces .nupkg + .snupkg in dist/)
+.\build\do_package.ps1
+
+# Push to local registry
+.\build\do_push_local.ps1
+
+# Push to prod (nuget.org)
+.\build\do_push_prod.ps1
+```
+
+### Direct dotnet commands
+
+```powershell
+# Restore
+dotnet restore src/Sa.slnx -c Release
+
+# Build
+dotnet build src/Sa.slnx -c Release -v n
+
+# Test (all)
+dotnet test src/Sa.slnx -v n
+
+# Test CI (skip tests requiring local Docker infrastructure)
+dotnet test src/Sa.slnx --filter "Category!=Local"
+```
+
+### GitHub Actions
+
+Workflow in `.github/workflows/` — builds on `main` branch push/PR. Uses `dotnet 9.x` runtime in CI (despite targeting net10.0). Note: tests are commented out in CI.
+
+---
+
+## Architecture Notes
+
+### Shared Code Pattern
+
+Common utilities live in `src/Sa/` and are linked into consuming projects via MSBuild ``. This avoids duplication while keeping projects independently buildable. Linked classes include:
+
+- `Classes/`: LockRenewer, MurmurHash3, Retry, ResetLazy, Section, MimeTypeMap, IArrayPool, LockRenewer
+- `Extensions/`: DateTimeExtensions, EnumerableExtensions, ExceptionExtensions, SpanExtensions, StringExtensions, NumericExtensions, StrToExtensions, GuidExtensions
+
+### Project Dependencies
+
+```
+Sa.Utils.WorkQueue → (none)
+Sa.Schedule → Sa.Utils.WorkQueue
+Sa.Outbox → Sa.Schedule
+Sa.Partitional.PostgreSql → Sa.Schedule + Sa.Data.PostgreSql
+Sa.Outbox.PostgreSql → Sa.Outbox + Sa.Partitional.PostgreSql (+ object pool, recycler mem stream)
+Sa.Data.S3 → (none, just Npgsql indirectly)
+Sa.HybridFileStorage → (base abstraction)
+Sa.HybridFileStorage.S3 → Sa.Data.S3 + Sa.HybridFileStorage
+Sa.Configuration → Microsoft.Extensions.Hosting
+Sa.Configuration.PostgreSql → (standalone)
+```
+
+### Common Properties (inherited by all packages)
+
+From `Common.Properties.xml`:
+- Target: `net10.0`
+- AOT: `PublishAot=true`, `IsAotCompatible=true`
+- Nullable: enabled
+- Analyzers: enabled
+- TrimmerSingleWarn: false
+- Symbols: included
+- License: MIT
+
+From `Common.NuGet.Properties.xml`: additional shared package references (logging, DI, SourceLink).
+
+### Testing Conventions
+
+- Framework: **xunit v3** (not classic xunit)
+- Integration tests use **Testcontainers** (PostgreSQL + Minio)
+- Test projects import `Host.Test.Properties.xml` for common test config
+- Local-dependent tests are tagged `Category!=Local` for CI
+
+---
+
+## Development Conventions
+
+- **ImplicitUsings** and **Nullable** enabled across all projects
+- **Central Package Management** — all versions in `Directory.Packages.props`
+- **SourceLink** enabled for debug symbol linking to GitHub
+- **InternalsVisibleTo** used for test project access to internal members
+- No `_editorconfig` rules beyond standard .NET conventions
+- All projects use SDK-style csproj format
+- Solution managed via `.slnx` (new solution format)
diff --git a/README-ru.md b/README-ru.md
new file mode 100644
index 00000000..fec05fa5
--- /dev/null
+++ b/README-ru.md
@@ -0,0 +1,260 @@
+# Sa — Набор инфраструктурных библиотек для .NET 10
+
+Нейрохерня - Серия переиспользуемых .NET 10-библиотек, сфокусированных на инфраструктурных паттернах для распределённых систем. Целевая платформа — **.NET 10.0**, используется **Native AOT**, применяется паттерн **Central Package Management (CPM)** через `Directory.Packages.props`.
+
+---
+
+### [Sa](src/Sa) — Общие утилиты
+
+Ядро экосистемы **Sa**: базовые классы и методы расширения, линкуемые в другие пакеты через ``. Целевая платформа — **.NET 10.0**, совместимость с **Native AOT**, нулевые внешние зависимости.
+
+
+Смотрите [полную документацию API](src/Sa/Readme.md).
+
+---
+
+### [Sa.Outbox.PostgreSql](src/Sa.Outbox.PostgreSql) — Реализация Outbox на PostgreSQL
+
+Реализация паттерна **Transactional Outbox** на PostgreSQL для гарантированной доставки сообщений в распределённых системах. Предотвращает потерю сообщений и гарантирует обработку даже при сбоях.
+
+- **Гарантированная доставка**: сообщения хранятся в БД до успешной обработки
+- **Параллельная обработка**: несколько воркеров безопасно конкурируют за задачи через `SKIP LOCKED`
+- **Мультитенантность**: изоляция и параллелизм по арендаторам
+- **Авто-масштабирование**: runtime-изменение параллелизма без перезапуска
+- **Планируемая очистка**: автоматическое удаление старых партиций
+- **Self-bootstrapping**: авто-регистрация настроек консьюмера при первом запуске
+- **Immutable настройки**: `OutboxConsumerSettings` record с fluent-билдером
+
+See [full README](src/Sa.Outbox.PostgreSql/Readme.md).
+
+---
+
+### [Sa.Partitional.PostgreSql](src/Sa.Partitional.PostgreSql) — Декларативное партиционирование PostgreSQL
+
+Объявление партицирования таблиц PostgreSQL (range: день/месяц/год; list) с автоматической миграцией, планированием очистки и in-memory кэшем.
+
+- **Range-партиционирование** по дню, месяцу или году с авто-именованием по timestamp
+- **List-партиционирование** по строковым/числовым ключам с иерархическими дочерними партициями
+- **Fluent-билдер** для объявления таблиц, настройки fillfactor, кастомных ограничений и миграций
+- **Автоматическая миграция** — предсоздание будущих партиций как фоновая задача
+- **Автоматическая очистка** — удаление старых партиций по настраиваемому окну удержания
+- **In-memory кэш** — избегает повторных запросов к каталогу; инвалидируется при runtime-изменениях
+- **StrOrNum** — discriminated union для типобезопасных значений ключей партиций
+
+See the full [Guide](src/Sa.Partitional.PostgreSql/Guide.md) and [API Reference](src/Sa.Partitional.PostgreSql/ApiReference.md).
+
+---
+
+### [Sa.Schedule](src/Sa.Schedule) — Планировщик задач
+
+Конфигурация и выполнение задач по расписанию — cron, интервалы, одноразовые запуски.
+
+| Возможность | Описание |
+|-------------|----------|
+| **Cron-тайминги** | Любое cron-выражение через `IJobTiming.FromCron()` |
+| **Интервальное расписание** | `EverySeconds`, `EveryMinutes`, `EveryHours`, `EveryDays` |
+| **Одноразовые задачи** | `RunOnce()` с опциональной начальной задержкой |
+| **Стратегии ошибок** | `CloseApplication`, `AbortJob`, `StopAllJobs`, `Ignore` |
+| **Повторные попытки** | Настраиваемое количество ретраев на ошибку |
+| **Интерцепторы** | Кросс логика через `IJobInterceptor` |
+| **Обработчики ошибок** | Глобальные `HandleError`-хендлеры на уровне планировщика |
+| **DI-интеграция** | `AddSaSchedule(Action)` с `BackgroundService` |
+
+```csharp
+builder.Services.AddSaSchedule(b => b
+ .AddJob()
+ .WithName("cleanup")
+ .EveryHours(1)
+ .ConfigureErrorHandling(eh => eh.IfErrorRetry(3).ThenAbortJob())
+);
+```
+
+---
+
+### [Sa.HybridFileStorage](src/Sa.HybridFileStorage) — Гибридное файловое хранилище
+
+Абстракция файлового хранилища с автоматическим failover между провайдерами (FileSystem ↔ S3 ↔ PostgreSQL).
+
+| Возможность | Описание |
+|-------------|----------|
+| **Мультипровайдер** | FileSystem, S3 (Minio), PostgreSQL — подключайте сколько угодно |
+| **Автоматический failover** | При недоступности одного провайдера — переход к следующему |
+| **Интерцепторы** | `before`, `after`, `onError` хуки на каждом провайдере |
+| **Пакетные операции** | `CopyToScopeBatchAsync` с параллелизмом и прогрессом |
+| **Расширения** | `CopyFromFileAsync`, `CopyToBasketAsync` для удобства |
+| **InMemory-провайдер** | Для тестирования: `AddSaInMemoryFileStorage()` |
+
+```csharp
+builder.Services.AddSaHybridFileStorage(cfg => cfg
+ .ConfigureStorage((sp, c) => c
+ .AddStorage(new FileSystemStorage("disk"))
+ .AddStorage(new S3Storage("s3"))
+ )
+);
+```
+
+---
+
+### [Sa.Configuration](src/Sa.Configuration) — Аргументы командной строки и секреты
+
+| Компонент | Назначение |
+|-----------|------------|
+| **Arguments** | Парсер CLI-аргументов в стиле dictionary — поддержка одиночных и множественных значений, типизированные геттеры (`GetBool`, `GetInt`, `GetTimeSpan` и т.д.) |
+| **Secrets** | Безопасное управление секретами из файлов, переменных окружения и генерируемых host-key файлов. Поддержка chained stores и environment-aware загрузки |
+
+```csharp
+var args = Arguments.CreateDefault();
+var dbPassword = args["db-password"]; // string?
+var timeout = args.GetTimeSpan("timeout"); // TimeSpan?
+```
+
+---
+
+### [Sa.Configuration.PostgreSql](src/Sa.Configuration.PostgreSql) — Динамическая конфигурация из PostgreSQL
+
+Добавляет источник конфигурации из БД — изменения отражаются в приложении без перекомпиляции и редеплоя.
+
+```csharp
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ connectionString: "Host=localhost;Database=myapp",
+ selectSql: "SELECT config_key, config_value FROM app_config",
+ parameters: Array.Empty()
+));
+```
+
+---
+
+### [Sa.Media](src/Sa.Media) — Асинхронное чтение WAV
+
+Памятно-эффективный асинхронный читатель WAV-файлов с конвертацией форматов.
+
+| Метод | Описание |
+|-------|----------|
+| `CreateFromFile(path)` | Открыть файл по пути |
+| `GetHeaderAsync()` | Считать WAV-заголовок |
+| `ReadSamplesPerChannelAsync()` | Потоковое чтение сэмплов по каналам |
+| `ReadDoubleSamplesAsync()` | Нормализованные double-сэмплы [-1..1] |
+| `ConvertToFormatAsync()` | Конвертация в PCM16/24/32, IEEE float |
+| `ReadStreamableChunksAsync()` | Чанки фиксированного размера для streaming |
+
+```csharp
+using var reader = AsyncWavReader.CreateFromFile("audio.wav");
+await foreach (var packet in reader.ReadDoubleSamplesAsync())
+{
+ Console.WriteLine($"Ch{packet.ChannelId}: {packet.Sample:F4}");
+}
+```
+
+---
+
+### [Sa.Media.FFmpeg](src/Sa.Media.FFmpeg) — Обёртка FFmpeg для .NET
+
+FFmpeg из коробки со встроенными бинарниками (Windows x64 + Linux) и DI.
+
+| Интерфейс | Назначение |
+|-----------|------------|
+| `IFFMpegExecutor` | Конвертация аудио/видео (PCM16LE, MP3, OGG) |
+| `IFFProbeExecutor` | Извлечение метаданных (длина, каналы, частота, битрейт) |
+| `IPcmS16LeChannelManipulator` | Разделение/объединение каналов |
+| `IFFMpegLocator` | Автопоиск исполняемого FFmpeg |
+
+```csharp
+builder.Services.AddSaFFMpeg();
+
+var probe = IFFProbeExecutor.Default;
+var meta = await probe.GetMetaInfo("input.mp3");
+Console.WriteLine($"Duration: {meta.Duration}s, Channels: {meta.Channels}");
+```
+
+---
+
+### [Sa.Data.PostgreSql](src/Sa.Data.PostgreSql) — Лёгкая обёртка Npgsql
+
+Без ORM-overhead, с DI, Native AOT и минимальными аллокациями.
+
+| Метод | Описание |
+|-------|----------|
+| `ExecuteNonQuery` | INSERT / UPDATE / DELETE / DDL с возвратом rowCount |
+| `ExecuteScalar / ExecuteScalarTyped` | Одиночное значение с авто-кастомом |
+| `ExecuteReader` | Потоковое чтение через callback (без загрузки в память) |
+| `ExecuteReaderList` | Сборка всех строк в `List` |
+| `ExecuteReaderFirst` | Первое значение первого столбца |
+| `ExecuteReaderSingle` | Безопасное scalar-значение |
+| `BeginBinaryImport` | Быстрый COPY BINARY для массового импорта |
+| `PgRetryStrategy` | Повторы с jitter для transient-ошибок Npgsql |
+
+---
+
+### [Sa.Utils.WorkQueue](src/Sa.Utils.WorkQueue) — Асинхронная очередь с ограничением параллелизма
+
+Высокопроизводительная очередь задач на базе `System.Threading.Channels` с ограниченной ёмкостью, динамическим контролем параллелизма и стратегиями масштабирования.
+
+| Возможность | Описание |
+|-------------|----------|
+| **Ограниченная очередь** | Back-pressure через `BoundedChannel` |
+| **Динамический параллелизм** | Изменяйте `ConcurrencyLimit` на лету |
+| **Стратегии масштабирования** | `Lifo` • `Fifo` • `RoundRobin` • `Random` |
+| **Стратегии ошибок** | `Continue`, `StopReader`, `ShutdownQueue` |
+| **Обратные вызовы статусов** | `Running` → `Completed` / `Faulted` / `Cancelled` / `Aborted` |
+| **Логирование без аллокаций** | `[LoggerMessage]` source generator |
+
+See [full README](src/Sa.Utils.WorkQueue/Readme.md).
+
+---
+
+## Образцы
+
+В `src/Samples/`:
+
+| Образец | Описание |
+|---------|----------|
+| [Configuration.Web](src/Samples/Configuration.Web) | CLI-аргументы + секреты в ASP.NET |
+| [FFmpeg.Console](src/Samples/FFmpeg.Console) | Извлечение метаданных FFmpeg |
+| [HybridFileStorage.Console](src/Samples/HybridFileStorage.Console) | Мульти-провайдерное хранилище |
+| [Partitional.ConsoleApp](src/Samples/Partitional.ConsoleApp) | Декларативное партиционирование |
+| [PgOutbox.ConsoleApp](src/Samples/PgOutbox.ConsoleApp) | Паттерн Outbox |
+| [Schedule.Console](src/Samples/Schedule.Console) | Планировщик задач |
+| [Storage.Tests](src/Samples/Storage.Tests) | Тесты гибридного хранилища |
+
+---
+
+## Тесты
+
+В `src/Tests/`: 15 тестовых проектов на **xunit v3** с **Testcontainers** (PostgreSQL + Minio) для интеграционных тестов.
+
+---
+
+## Сборка
+
+```powershell
+# Полная сборка
+.\build\do_build.ps1
+
+# Запуск тестов
+.\build\do_test.ps1
+
+# Создание NuGet-пакетов
+.\build\do_package.ps1
+```
+
+Прямые команды dotnet:
+
+```powershell
+dotnet restore src/Sa.slnx -c Release
+dotnet build src/Sa.slnx -c Release -v n
+dotnet test src/Sa.slnx -v n
+```
+
+---
+
+## Архитектура
+
+- Целевая платформа — **.NET 10.0** с **Native AOT**
+- **Central Package Management** — версии в `Directory.Packages.props`
+- Общие утилиты в **Sa** линкуются в consuming-проект через ``
+- Все пакеты используют SDK-style csproj с implicit usings, nullable и анализаторами
+- Решение управляется через `.slnx`
+
+## Лицензия
+
+MIT
diff --git a/README.md b/README.md
index 0142ee8f..5f0589ce 100644
--- a/README.md
+++ b/README.md
@@ -1,70 +1,290 @@
-# sa
+# Sa — .NET 10 Infrastructure Libraries
-dot net10 experimental aot project
+Reusable infrastructure libraries for distributed .NET 10 systems — **Native AOT compatible**, **nullable enabled**, built on modern .NET primitives.
+---
-## [Sa.Outbox.PostgreSql](src/Sa.Outbox.PostgreSql)
+## Libraries
-Designed for implementing the Outbox pattern using PostgreSQL, which is used to ensure reliable message delivery in distributed systems. It helps prevent message loss and guarantees that messages will be processed even in the event of failures.
+### [Sa](src/Sa) — Shared Utilities
-- Reliable message delivery: Ensures that messages are stored in the database until they are successfully processed.
-- Parallel processing: Enables messages to be processed in parallel, increasing system performance.
-- Flexibility: Supports various types of messages and their handlers.
-- Tenant support: Allows for even distribution of load.
-- Data cleaning: scheduled deletion of old data.
+Core utility library consumed by other packages via ``. Targets **.NET 10.0**, **Native AOT compatible**, zero external dependencies.
-## [Sa.Partitional.PostgreSql](src/Sa.Partitional.PostgreSql)
+See [full API reference](src/Sa/Readme.md).
-A library designed for managing table partitioning in PostgreSQL with the aim of improving performance and manageability for large volumes of data.
+---
-- Declaratively describe a partitioned table by time (day, month, year).
-- Define partitions based on lists of keys for rows or numbers.
-- Set a schedule for migrations to create new partitions.
-- Set a schedule for deleting old partitions.
-- Manage partitions.
+### [Sa.Configuration](src/Sa.Configuration) — CLI Arguments & Secrets
-## [Sa.Schedule](src/Sa.Schedule)
+| Type | Purpose |
+|------|---------|
+| `Arguments` | Command-line argument parser — dictionary-like access, typed getters (`GetBool`, `GetInt`, `GetTimeSpan`, etc.) |
+| `Secrets` | Secure secrets management from files, environment variables, and host-key files. Supports chained stores and templating (`${secret:key}`) |
-`Sa.Schedule` provides a way to configure and execute tasks on a schedule.
+```csharp
+// Arguments
+var args = new Arguments(argsArray);
+var port = args.GetInt("port") ?? 8080;
-- It allows you to manage a set of tasks that will be executed at specific times or at defined intervals.
-- You can start and stop tasks.
-- Define failure strategies: close the application, stop job, stop all jobs, or ignore the failure.
+// Secrets
+var secrets = Secrets.CreateDefault();
+var populated = secrets.PopulateSecrets("Host={db_host};Password=${db_password}");
+```
-## [Sa.HybridFileStorage](src/Sa.HybridFileStorage)
+---
-`IHybridFileStorage` - interface designed for hybrid file storage systems that facilitates the management of file operations, ensuring reliable and resilient access to files across multiple storage providers.
+### [Sa.Configuration.PostgreSql](src/Sa.Configuration.PostgreSql) — Dynamic DB Configuration
-- Supports file operations such as uploading, downloading, and deleting files.
-- Integrates multiple storage providers (e.g., file system, s3, PostgreSQL) for enhanced reliability.
-- Automatically switches between providers in case one becomes unavailable, ensuring continuous access to files.
-- Promotes improved resilience and availability of file data in applications requiring dependable storage management.
+PostgreSQL-backed `IConfigurationSource` — changes in the database reflect in-app without redeploy.
-## [Sa.Configuration](src/Sa.Configuration)
+```csharp
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ connectionString: "Host=localhost;Database=myapp",
+ selectSql: "SELECT key, value FROM app_config",
+ parameters: Array.Empty()));
+```
-- `Arguments` class parses command-line arguments in a C# application, enabling easy retrieval of parameter values through a dictionary-like interface. It supports both single-value and multi-value parameters for flexible command-line configurations.
-- `Secrets` class securely manages sensitive information, such as API keys and database passwords, from various sources. It can load secrets from files, environment variables, and dynamically generated host key files.
+Supports parameterised queries and `PgRetryStrategy` for transient error handling.
-## [Sa.Configuration.PostgreSql](src/Sa.Configuration.PostgreSql)
+---
-`AddPostgreSqlConfiguration` extension method allows you to add a PostgreSQL-based configuration source to an IConfigurationBuilder.
+### [Sa.Data.PostgreSql](src/Sa.Data.PostgreSql) — Lightweight Npgsql Wrapper
-- This setup allows for dynamic configuration management, where changes in the database can be reflected in the application without needing to recompile or redeploy.
+Thin wrapper over Npgsql for typical database operations — zero ORM overhead, Native AOT friendly.
-## [Sa.Media](src/Sa.Media)
+| Method | Description |
+|--------|-------------|
+| `ExecuteNonQueryAsync` | INSERT / UPDATE / DELETE / DDL with row count return |
+| `ExecuteScalarAsync` / `ExecuteScalarTypedAsync` | Single value with auto-cast |
+| `ExecuteReaderAsync` | Streaming row reading via callback (no full result in memory) |
+| `ExecuteReaderListAsync` | Collect all rows into `List` |
+| `ExecuteReaderFirstAsync` | First column of first row (Guid, TimeSpan, DateTime, int, long, etc.) |
+| `ExecuteReaderSingleAsync` / `TryExecuteReaderSingleAsync` | Safe scalar with nullability |
+| `ExecuteTransactionAsync` | Atomic operations with auto commit/rollback |
+| `BeginBinaryImportAsync` | Fast COPY BINARY for bulk inserts |
+| `PgRetryStrategy` | Retry with jitter for transient Npgsql errors |
-- `AsyncWavReader` async and memory-efficient WAV file reader for .NET
+DI registration: `AddSaPostgreSqlDataSource()`.
-## [Sa.Media.FFmpeg](src/Sa.Media.FFmpeg)
+---
-FFmpeg .NET Wrapper - ready to use out of the box with minimal setup
+### [Sa.Data.S3](src/Sa.Data.S3) — S3 Data Client
-- Extract metadata from media files (duration, channels, sample rate, etc.)
-- Convert audio to: WAV, MP3, MP4, OGG ..
-- Splits/Join audio file by channels
-- Built-in FFmpeg binaries for Windows x64 and Linux
-- Supports Dependency Injection (DI) via standard IServiceCollection integration
+Minio-compatible S3 client for data operations.
-## Sa.Utils
+---
-- [Sa.Utils.WorkQueue](src/Sa.Utils.WorkQueue) - async Queue with Concurrency Limiting
\ No newline at end of file
+### [Sa.Outbox](src/Sa.Outbox) — Transactional Outbox Core
+
+Base infrastructure for the **Transactional Outbox** pattern — guarantees atomic message recording alongside business operations within a single database transaction, with reliable delivery, retries, blocking, multi-threading, and multi-tenancy support.
+
+Defines abstractions; concrete DB work (PostgreSQL, SQL Server, etc.) is implemented by providers (`Sa.Outbox.PostgreSql`, `Sa.Outbox.SqlServer`).
+
+| Key Type | Purpose |
+|----------|---------|
+| `IOutboxBuilder` | Fluent configuration builder |
+| `IOutboxMessagePublisher` | Publish messages to outbox |
+| `IConsumer` | Message consumer interface |
+| `IOutboxContextOperations` | Delivery status change operations (`Ok`, `Error`, `Warn`, `Postpone`, etc.) |
+| `OutboxConsumerSettings` | Immutable snapshot of consumer group settings (interval, batches, concurrency, retries…) |
+| `OutboxConsumerSettingsBuilder` | Fluent builder for creating/updating `OutboxConsumerSettings` |
+| `IOutboxConsumerManager` | Runtime manager: atomic swap, pause/resume, change subscriptions |
+| `IDeliverySnapshot` | Read-only view of registered deliveries for diagnostics |
+| `DeliveryStatus` / `DeliveryStatusCode` | HTTP-like delivery status codes |
+| `ExponentialBackoffRetryStrategy` | Exponential backoff with jitter |
+
+See individual provider READMEs for full usage examples.
+
+---
+
+### [Sa.Outbox.PostgreSql](src/Sa.Outbox.PostgreSql) — PostgreSQL Provider
+
+Production-ready PostgreSQL implementation with UUID v7 IDs, BINARY COPY bulk insertion, `SKIP LOCKED` concurrent consumption, advisory locks for offset coordination, and automated partition migration/cleanup.
+
+See [full README](src/Sa.Outbox.PostgreSql/Readme.md).
+
+---
+
+### [Sa.Partitional.PostgreSql](src/Sa.Partitional.PostgreSql) — Declarative Partitioning
+
+Declarative PostgreSQL table partitioning for .NET 10 — range (day/month/year) and list partitioning with automated migration, cleanup scheduling, and in-memory caching.
+
+- **Range partitioning** by day, month, or year with automatic timestamp-based naming
+- **List partitioning** by string or numeric keys with hierarchical child partitions
+- **Fluent builder API** for declaring tables, tuning fillfactor, custom constraints, and migrations
+- **Automated migration** — pre-create future partitions as a background job
+- **Automated cleanup** — drop old partitions past a configurable retention window
+- **In-memory cache** — avoids repeated catalog queries; auto-invalidates on runtime changes
+- **StrOrNum** discriminated union for type-safe partition key values
+
+See [Guide](src/Sa.Partitional.PostgreSql/Guide.md) and [API Reference](src/Sa.Partitional.PostgreSql/ApiReference.md).
+
+---
+
+### [Sa.Schedule](src/Sa.Schedule) — Scheduled Task Executor
+
+Configurable and executable scheduled tasks with failure strategies.
+
+| Feature | Description |
+|---------|-------------|
+| **Flexible timing** | Cron expressions, fixed intervals (seconds/minutes/hours/days), one-shot delays |
+| **Failure strategies** | `CloseApplication`, `AbortJob`, `StopAllJobs`, or `Ignore` |
+| **Retry on failure** | Configurable retry count per job |
+| **Concurrency control** | Per-job `ConcurrencyLimit` and `MaxConcurrency` |
+| **Interceptors** | `IJobInterceptor` for pre/post execution hooks |
+| **Error handlers** | Global `Func` error handlers |
+| **Runtime management** | Start, stop, restart individual schedulers via `IScheduler` |
+
+```csharp
+builder.Services.AddSaSchedule(builder => builder
+ .UseHostedService()
+ .AddJob()
+ .WithName("cleanup")
+ .EveryHours(1)
+ .ConfigureErrorHandling(eh => eh.IfErrorRetry(3).ThenAbortJob()));
+```
+
+---
+
+### [Sa.HybridFileStorage](src/Sa.HybridFileStorage) — Multi-Provider File Storage
+
+`IHybridFileStorage` abstracts file operations across multiple storage providers (FileSystem, S3, PostgreSQL) with automatic failover.
+
+| Capability | Description |
+|------------|-------------|
+| **Upload / Download / Delete** | Standard file operations with streaming |
+| **Multi-provider** | Register any `IFileStorage` implementation |
+| **Automatic failover** | Tries providers sequentially; aggregates errors if all fail |
+| **Batch operations** | Parallel batch upload/download with progress reporting |
+| **Interceptors** | Pre/post/on-error hooks per provider |
+| **Built-in providers** | `InMemoryFileStorage` (testing), plus `FileSystem`, `S3`, `Postgres` in separate packages |
+
+```csharp
+builder.Services.AddSaHybridFileStorage(cfg => cfg
+ .ConfigureStorage(sp => sp
+ .AddStorage(new FileSystemStorage("/data/uploads"))
+ .AddStorage(new S3Storage("s3-bucket"))));
+```
+
+Providers: [`Sa.HybridFileStorage.FileSystem`](src/Sa.HybridFileStorage.FileSystem), [`Sa.HybridFileStorage.S3`](src/Sa.HybridFileStorage.S3), [`Sa.HybridFileStorage.Postgres`](src/Sa.HybridFileStorage.Postgres).
+
+---
+
+### [Sa.Media](src/Sa.Media) — Async WAV Reader
+
+Memory-efficient, fully async WAV file reader built on `System.IO.Pipelines`.
+
+| Method | Description |
+|--------|-------------|
+| `CreateFromFile` / `Create(Stream)` | Factory methods |
+| `GetHeaderAsync` | Parse WAV header |
+| `ReadSamplesPerChannelAsync` | Raw bytes per channel |
+| `ReadDoubleSamplesAsync` | Normalized double samples |
+| `ConvertToFormatAsync` | Convert to PCM16/24/32, IEEE float |
+| `ReadStreamableChunksAsync` | Streaming chunks with configurable batch size |
+
+```csharp
+using var reader = AsyncWavReader.CreateFromFile("audio.wav");
+var header = await reader.GetHeaderAsync();
+await foreach (var packet in reader.ReadDoubleSamplesAsync())
+{
+ Console.WriteLine($"Ch{packet.ChannelId}: {packet.Sample}");
+}
+```
+
+---
+
+### [Sa.Media.FFmpeg](src/Sa.Media.FFmpeg) — FFmpeg .NET Wrapper
+
+Ready-to-use FFmpeg integration with built-in binaries (Windows x64 + Linux) and DI support.
+
+| Interface | Purpose |
+|-----------|---------|
+| `IFFMpegExecutor` | Audio/video conversion (PCM16LE, MP3, OGG) |
+| `IFFProbeExecutor` | Metadata extraction (duration, channels, sample rate, bitrate) |
+| `IPcmS16LeChannelManipulator` | Channel split/join operations |
+| `IFFMpegLocator` | Auto-discovery of FFmpeg executable |
+
+```csharp
+builder.Services.AddSaFFMpeg();
+
+var probe = IFFProbeExecutor.Default;
+var meta = await probe.GetMetaInfo("input.mp3");
+Console.WriteLine($"Duration: {meta.Duration}s, Channels: {meta.Channels}");
+```
+
+---
+
+### [Sa.Utils.WorkQueue](src/Sa.Utils.WorkQueue) — Async Queue with Concurrency Limiting
+
+High-performance task queue built on `System.Threading.Channels` with bounded capacity, dynamic concurrency scaling, and multiple reader-scaling strategies.
+
+| Feature | Description |
+|---------|-------------|
+| **Bounded queue** | Back-pressure via `BoundedChannel` — overflow handled by `Wait`, `DropWrite`, `DropOldest` |
+| **Dynamic concurrency** | Change `ConcurrencyLimit` at runtime |
+| **Scaling strategies** | `Lifo` • `Fifo` • `RoundRobin` • `Random` |
+| **Error strategies** | `Continue`, `StopReader`, `ShutdownQueue` |
+| **Status callbacks** | `Running` → `Completed` / `Faulted` / `Cancelled` / `Aborted` |
+| **Zero-allocation logging** | `[LoggerMessage]` source generator |
+
+See [full README](src/Sa.Utils.WorkQueue/Readme.md).
+
+---
+
+## Samples
+
+Located in `src/Samples/`:
+
+| Sample | Description |
+|--------|-------------|
+| [Configuration.Web](src/Samples/Configuration.Web) | CLI args + secrets in ASP.NET |
+| [FFmpeg.Console](src/Samples/FFmpeg.Console) | FFmpeg metadata extraction |
+| [HybridFileStorage.Console](src/Samples/HybridFileStorage.Console) | Multi-provider file storage |
+| [Partitional.ConsoleApp](src/Samples/Partitional.ConsoleApp) | Declarative partitioning |
+| [PgOutbox.ConsoleApp](src/Samples/PgOutbox.ConsoleApp) | Outbox pattern demo |
+| [Schedule.Console](src/Samples/Schedule.Console) | Scheduled task executor |
+| [Storage.Tests](src/Samples/Storage.Tests) | Hybrid file storage tests |
+
+---
+
+## Tests
+
+Located in `src/Tests/`: 15 test projects using **xunit v3** and **Testcontainers** (PostgreSQL + Minio) for integration tests.
+
+---
+
+## Building
+
+```powershell
+# Full build
+.\build\do_build.ps1
+
+# Run tests
+.\build\do_test.ps1
+
+# Package NuGet packages
+.\build\do_package.ps1
+```
+
+Direct dotnet commands:
+
+```powershell
+dotnet restore src/Sa.slnx -c Release
+dotnet build src/Sa.slnx -c Release -v n
+dotnet test src/Sa.slnx -v n
+```
+
+---
+
+## Architecture
+
+- Targets **.NET 10.0** with **Native AOT**
+- Uses **Central Package Management** (`Directory.Packages.props`)
+- Shared utilities in **Sa** are linked into consuming projects
+- All packages use SDK-style csproj with implicit usings, nullable, and analyzers
+- Solution managed via `.slnx`
+
+## License
+
+MIT
diff --git a/src/Directory.Packages.props b/src/Directory.Packages.props
index 79e17c72..a7086e1f 100644
--- a/src/Directory.Packages.props
+++ b/src/Directory.Packages.props
@@ -23,6 +23,5 @@
-
diff --git a/src/Sa.Configuration.PostgreSql/DatabaseConfigurationProvider.cs b/src/Sa.Configuration.PostgreSql/DatabaseConfigurationProvider.cs
index a033bf0c..b2f5ffb3 100644
--- a/src/Sa.Configuration.PostgreSql/DatabaseConfigurationProvider.cs
+++ b/src/Sa.Configuration.PostgreSql/DatabaseConfigurationProvider.cs
@@ -2,12 +2,13 @@
using Microsoft.Extensions.Configuration;
using Sa.Data.PostgreSql;
-using System.Threading;
+
///
/// Configuration provider that loads settings from a PostgreSQL database.
///
-public sealed class DatabaseConfigurationProvider(PostgreSqlConfigurationOptions options) : ConfigurationProvider
+public sealed class DatabaseConfigurationProvider(PostgreSqlConfigurationOptions options)
+ : ConfigurationProvider
{
///
/// Loads configuration from PostgreSQL database.
@@ -15,16 +16,16 @@ public sealed class DatabaseConfigurationProvider(PostgreSqlConfigurationOptions
public override void Load()
{
PgRetryStrategy
- .ExecuteWithRetry(async _ => await LoadAsync(options))
+ .ExecuteWithRetry(async _ => await LoadAsync())
.AsTask()
.GetAwaiter()
.GetResult();
}
///
- /// Loads configuration from PostgreSQL database asynchronously.
+ /// Asynchronously loads configuration from PostgreSQL database.
///
- private async Task LoadAsync(PostgreSqlConfigurationOptions options)
+ private async Task LoadAsync()
{
try
{
diff --git a/src/Sa.Configuration.PostgreSql/Readme-ru.md b/src/Sa.Configuration.PostgreSql/Readme-ru.md
new file mode 100644
index 00000000..4fe8a000
--- /dev/null
+++ b/src/Sa.Configuration.PostgreSql/Readme-ru.md
@@ -0,0 +1,129 @@
+# Sa.Configuration.PostgreSql
+
+Динамический источник конфигурации для .NET, загружающий настройки из PostgreSQL. Изменения в БД применяются к работающему приложению без перезапуска — достаточно вызвать `Reload()` на `IConfigurationRoot`.
+
+---
+
+## Возможности
+
+- **Живая конфигурация**: значения хранятся в БД и могут быть изменены во время выполнения
+- **Параметризированные SQL-запросы**: поддержка `@named_parameters` через `NpgsqlParameter`
+- **Автоматические повторы**: встроенная стратегия повторов (`PgRetryStrategy`) с детекцией транзитных ошибок Npgsql
+- **Обрезка ключей/значений**: пробелы автоматически обрезаются и у ключей, и у значений
+- **Безопасная обработка NULL**: `NULL` в БД → `null` в конфиге; пустая строка → `string.Empty`
+
+---
+
+## Публичный API
+
+| Тип | Назначение |
+|-----|-----------|
+| `PostgreSqlConfigurationOptions` | Immutable record: `ConnectionString`, `SelectSql`, `Parameters` |
+| `DatabaseConfigurationSource` | Реализация `IConfigurationSource` |
+| `DatabaseConfigurationProvider` | `ConfigurationProvider`, загружающий пары ключ-значение из БД |
+| `Setup.AddSaPostgreSqlConfiguration()` | Метод-расширение для `IConfigurationBuilder` |
+
+---
+
+## Быстрый старт
+
+```csharp
+using Sa.Configuration.PostgreSql;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ ConnectionString: "Host=localhost;Database=myapp;Username=app;Password=secret",
+ SelectSql: "SELECT key, value FROM app_settings"
+));
+
+var app = builder.Build();
+
+// Чтение настроек
+var theme = app.Configuration["theme"]; // → "dark"
+var lang = app.Configuration["language"]; // → "en"
+```
+
+---
+
+## Параметризированные запросы
+
+Используйте `@parameters` для фильтрации по клиенту/арендатору:
+
+```csharp
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ ConnectionString: "...",
+ SelectSql: "SELECT key, value FROM client_settings WHERE client_id = @client_id",
+ Parameters: [new NpgsqlParameter("client_id", "acme-corp")]
+));
+```
+
+---
+
+## Обновления живой конфигурации
+
+Когда строки в таблице `app_settings` изменяются, приложение может подхватить новые значения:
+
+```csharp
+// После изменения строк в базе данных:
+((IConfigurationRoot)app.Configuration).Reload();
+
+// Или вручную:
+provider.Reload(); // DatabaseConfigurationProvider реализует IConfigurationProvider
+```
+
+---
+
+## Поведение загрузки
+
+| Сценарий | Результат |
+|----------|----------|
+| Ключ пустой или состоит только из пробелов | Пропускается |
+| Значение `NULL` в БД | Сохраняется как `null` |
+| Значение пустая строка в БД | Сохраняется как `string.Empty` |
+| Ошибка подключения | `InvalidOperationException` с оригинальным исключением как `InnerException` |
+
+---
+
+## Схема таблицы
+
+Минимальная таблица, необходимая для провайдера:
+
+```sql
+CREATE TABLE app_settings (
+ key VARCHAR PRIMARY KEY,
+ value TEXT
+);
+
+-- Пример данных
+INSERT INTO app_settings (key, value) VALUES
+ ('theme', 'dark'),
+ ('language', 'en'),
+ ('debug_mode', ''); -- пустая строка
+```
+
+---
+
+## Зависимости
+
+- `Microsoft.Extensions.Configuration`
+- `Sa.Data.PostgreSql` (обёртка Npgsql с PgRetryStrategy и IPgDataSource)
+
+---
+
+## Структура проекта
+
+```
+src/Sa.Configuration.PostgreSql/
+├── PostgreSqlConfigurationOptions.cs # Record опций
+├── DatabaseConfigurationSource.cs # IConfigurationSource
+├── DatabaseConfigurationProvider.cs # ConfigurationProvider + повторы
+├── Setup.cs # Метод-расширение AddSaPostgreSqlConfiguration()
+└── Readme.md # ← вы здесь
+```
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.Configuration.PostgreSql/Readme.md b/src/Sa.Configuration.PostgreSql/Readme.md
index f96a96f6..b66b721b 100644
--- a/src/Sa.Configuration.PostgreSql/Readme.md
+++ b/src/Sa.Configuration.PostgreSql/Readme.md
@@ -1,32 +1,105 @@
# Sa.Configuration.PostgreSql
-The `AddPostgreSqlConfiguration` extension method allows you to add a PostgreSQL-based configuration source to an IConfigurationBuilder. This enables your application to load configuration settings directly from a PostgreSQL database.
+A dynamic configuration source for .NET that loads settings from PostgreSQL. Changes in the database are applied to the running application without restart — just call `Reload()` on `IConfigurationRoot`.
-## Key Components
-- PostgreSqlConfigurationOptions: A record that holds the connection string, SQL query, and optional parameters for querying the database.
-- DatabaseConfigurationSource: Implements IConfigurationSource and creates a DatabaseConfigurationProvider to fetch configuration data.
-- DatabaseConfigurationProvider: Inherits from ConfigurationProvider and overrides the Load method to execute the SQL query and populate the configuration data.
+## Features
+
+- **Live configuration**: values are stored in the database and can be changed at runtime
+- **Parameterized SQL queries**: supports `@named_parameters` via `NpgsqlParameter`
+- **Automatic retry**: built-in retry strategy (`PgRetryStrategy`) with detection of Npgsql transient errors
+- **Key/value trimming**: whitespace is automatically trimmed from both keys and values
+- **Safe NULL handling**: `NULL` in DB → `null` in config; empty string → `string.Empty`
+
+## Public API
+
+| Type | Purpose |
+|------|---------|
+| `PostgreSqlConfigurationOptions` | Immutable record: `ConnectionString`, `SelectSql`, `Parameters` |
+| `DatabaseConfigurationSource` | `IConfigurationSource` implementation |
+| `DatabaseConfigurationProvider` | `ConfigurationProvider` that loads key-value pairs from DB |
+| `Setup.AddSaPostgreSqlConfiguration()` | Extension method for `IConfigurationBuilder` |
+
+## Quick Start
-## Example Usage
```csharp
-using Microsoft.Extensions.Configuration;
using Sa.Configuration.PostgreSql;
-var builder = new ConfigurationBuilder();
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ ConnectionString: "Host=localhost;Database=myapp;Username=app;Password=secret",
+ SelectSql: "SELECT key, value FROM app_settings"
+));
+
+var app = builder.Build();
+
+// Reading settings
+var theme = app.Configuration["theme"]; // → "dark"
+var lang = app.Configuration["language"]; // → "en"
+```
+
+## Parameterized Queries
+
+Use `@parameters` for filtering by client/tenant:
+
+```csharp
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ ConnectionString: "...",
+ SelectSql: "SELECT key, value FROM client_settings WHERE client_id = @client_id",
+ Parameters: [new NpgsqlParameter("client_id", "acme-corp")]
+));
+```
+
+## Live Configuration Updates
-// Define PostgreSqlConfigurationOptions
-var options = new PostgreSqlConfigurationOptions(
- "Host=my_host;Database=my_db;Username=my_user;Password=my_pw",
- "SELECT key, value FROM configuration"
+When rows in the `app_settings` table change, the application can pick up new values:
+
+```csharp
+// After modifying rows in the database:
+((IConfigurationRoot)app.Configuration).Reload();
+
+// Or manually:
+provider.Reload(); // DatabaseConfigurationProvider implements IConfigurationProvider
+```
+
+## Load Behavior
+
+| Scenario | Result |
+|----------|--------|
+| Key is empty or whitespace only | Skipped |
+| Value is `NULL` in DB | Stored as `null` |
+| Value is an empty string in DB | Stored as `string.Empty` |
+| Connection error | `InvalidOperationException` with the original exception as `InnerException` |
+
+## Table Schema
+
+Minimum table required for the provider:
+
+```sql
+CREATE TABLE app_settings (
+ key VARCHAR PRIMARY KEY,
+ value TEXT
);
-// Add PostgreSQL configuration to the builder
-builder.AddSaPostgreSqlConfiguration(options);
+-- Sample data
+INSERT INTO app_settings (key, value) VALUES
+ ('theme', 'dark'),
+ ('language', 'en'),
+ ('debug_mode', ''); -- empty string
+```
+
+## Dependencies
+
+- `Microsoft.Extensions.Configuration`
+- `Sa.Data.PostgreSql` (Npgsql wrapper with PgRetryStrategy and IPgDataSource)
-// Build the configuration
-var configuration = builder.Build();
+## Project Layout
-// Access configuration values
-string setting1 = configuration["Setting1"];
-Console.WriteLine($"Setting1: {setting1}");
+```
+src/Sa.Configuration.PostgreSql/
+├── PostgreSqlConfigurationOptions.cs # Options record
+├── DatabaseConfigurationSource.cs # IConfigurationSource
+├── DatabaseConfigurationProvider.cs # ConfigurationProvider + retry
+├── Setup.cs # Extension method AddSaPostgreSqlConfiguration()
+└── Readme.md # ← you are here
```
diff --git a/src/Sa.Configuration.PostgreSql/Sa.Configuration.PostgreSql.csproj b/src/Sa.Configuration.PostgreSql/Sa.Configuration.PostgreSql.csproj
index af0b5247..546a04fe 100644
--- a/src/Sa.Configuration.PostgreSql/Sa.Configuration.PostgreSql.csproj
+++ b/src/Sa.Configuration.PostgreSql/Sa.Configuration.PostgreSql.csproj
@@ -3,7 +3,7 @@
- 0.9.1
+ 0.10.0
add a PostgreSQL-based configuration source to IConfiguration
diff --git a/src/Sa.Configuration/CommandLine/Readme-ru.md b/src/Sa.Configuration/CommandLine/Readme-ru.md
new file mode 100644
index 00000000..0c35bb1f
--- /dev/null
+++ b/src/Sa.Configuration/CommandLine/Readme-ru.md
@@ -0,0 +1,208 @@
+# Arguments — Парсинг аргументов командной строки
+
+Парсинг и потребление аргументов командной строки в .NET-приложениях через простой dictionary-like API. Поддерживает форматы `--flag=value`, `--flag value`, короткие опции (`-x`) и типизированные геттеры.
+
+> **Важно:** парсер удаляет ведущие тире из имён параметров. При обращении к значению используйте ключ **без** лидирующих `-` или `--`.
+> Пример: `--config_db` в CLI → `args["config_db"]` в коде. `-v` в CLI → `args["v"]` в коде.
+
+## Быстрый старт
+
+```csharp
+using Sa.Configuration.CommandLine;
+
+// Парсим args (по умолчанию берёт Environment.GetCommandLineArgs())
+var args = new Arguments(args);
+
+// Доступ через индексатор (возвращает null, если ключ отсутствует) — ключи без ведущих тире
+string? db = args["config_db"];
+string? file = args["config_file"];
+bool debug = args.IsPresent("debug"); // true если флаг присутствует и истинен
+
+// Типизированные помощники (возвращают nullable, null при отсутствии/невалидности)
+int? port = args.GetInt("port");
+float? timeout = args.GetFloat("timeout");
+long offset = args.GetLong("offset");
+TimeSpan ttl = args.GetTimeSpan("ttl");
+bool verbose = args.GetBool("v"); // "true"/"1"/"yes"/"on" → true
+```
+
+### Минимальное консольное приложение
+
+```csharp
+using Sa.Configuration.CommandLine;
+
+var arguments = new Arguments(args);
+
+Console.WriteLine($"БД: {arguments["db"] ?? "(по умолчанию)"}");
+Console.WriteLine($"Порт: {arguments.GetInt("port") ?? 5432}");
+Console.WriteLine($"Debug: {arguments.IsPresent("debug")}");
+Console.WriteLine($"TTL: {arguments.GetTimeSpan("ttl") ?? TimeSpan.Zero}");
+```
+
+Запуск:
+
+```bash
+dotnet run -- --db mydb --port 9999 --debug --ttl 00:05:00 -v
+```
+
+Вывод:
+
+```
+БД: mydb
+Порт: 9999
+Debug: True
+TTL: 00:05:00
+```
+
+---
+
+## Поддерживаемые форматы
+
+| Формат | Ввод в CLI | Ключ в словаре | Значение |
+|--------|-----------|---------------|---------|
+| Длинный флаг + пробел | `--key value` | `"key"` | `"value"` |
+| Равно | `--key=value` | `"key"` | `"value"` |
+| Короткий флаг + пробел | `-k value` | `"k"` | `"value"` |
+| Короткое равно | `-k=v` | `"k"` | `"v"` |
+| Булев флаг | `--debug` | `"debug"` | `"true"` |
+| Значение в кавычках | `--name "hello world"` | `"name"` | `"hello world"` |
+
+---
+
+## Справочник API
+
+### Конструктор
+
+```csharp
+public Arguments(params IReadOnlyList args)
+```
+
+Создаёт экземпляр из списка строк аргументов.
+
+### Статическая фабрика
+
+```csharp
+public static Arguments CreateDefault(string[]? args = null)
+```
+
+Шорткат, который использует `Environment.GetCommandLineArgs()` когда `args` равен null.
+
+```csharp
+var args = Arguments.CreateDefault(); // читает Process.GetCurrentProcess().CommandLine
+```
+
+### Индексатор
+
+```csharp
+public string? this[string param] { get; }
+```
+
+Возвращает значение по имени параметра или `null`, если не найдено. Ключи хранятся без ведущих тире.
+
+```csharp
+var db = args["database"]; // null если --database никогда не передавали
+```
+
+### Contains / IsPresent
+
+```csharp
+public bool Contains(string param) // true если ключ существует (даже если значение пустое)
+public bool IsPresent(string param) // true если ключ существует И значение не null
+```
+
+`IsPresent` различает отсутствующий флаг и присутствующий, но пустой.
+
+### Типизированные геттеры
+
+Все возвращают `T?` (nullable) и дают `null` когда параметр отсутствует или не распарсивается.
+
+| Метод | Тип возврата | Пример |
+|-------|-------------|--------|
+| `GetBool(string)` | `bool?` | `args.GetBool("verbose")` — принимает `true/1/yes/on` |
+| `GetInt(string)` | `int?` | `args.GetInt("port")` |
+| `GetFloat(string)`| `float?`| `args.GetFloat("ratio")` |
+| `GetLong(string)` | `long?` | `args.GetLong("offset")` |
+| `GetTimeSpan(string)` | `TimeSpan?` | `args.GetTimeSpan("delay")` |
+
+Все числовые парсинги используют `CultureInfo.InvariantCulture`.
+
+### Исходные параметры
+
+```csharp
+public IReadOnlyDictionary Parameters { get; }
+```
+
+Возвращает полный словарь распарсенных параметров. Ключи хранятся без ведущих тире.
+
+---
+
+## Интеграция с Microsoft.Extensions.Configuration
+
+Регистрация аргументов командной строки как источника `IConfiguration`:
+
+```csharp
+using Microsoft.Extensions.Configuration;
+using Sa.Configuration.CommandLine;
+
+var configuration = new ConfigurationBuilder()
+ .AddSaCommandLine(args) // <-- добавляет CLI аргументы как источник конфига
+ .AddJsonFile("appsettings.json", optional: true)
+ .Build();
+
+// Доступ через индексатор IConfiguration — ключи тоже без тире
+var db = configuration["db"];
+var port = configuration["port"];
+```
+
+Порядок важен: источники, зарегистрированные **позже**, переопределяют ранние. Размещайте `AddSaCommandLine` перед JSON/файловыми источниками, если хотите, чтобы CLI имел приоритет:
+
+```csharp
+new ConfigurationBuilder()
+ .AddJsonFile("appsettings.json") // базовые значения по умолчанию
+ .AddSaCommandLine(args) // переопределения из CLI
+ .Build();
+```
+
+---
+
+## Запуск приложения
+
+### Из терминала
+
+```bash
+# Длинные флаги с разделителем пробелом
+dotnet run --project MyApp.dll --db production --port 5432 --debug
+
+# Синтаксис с равно
+dotnet run --project MyApp.dll --db=production --port=5432
+
+# Смешанные форматы
+dotnet run -- -d --db=prod -p 3306 --ttl 30s
+```
+
+### Из Visual Studio / VS Code
+
+Установите аргументы в launchSettings.json:
+
+```json
+{
+ "profiles": {
+ "MyApp": {
+ "commandName": "Project",
+ "commandLineArgs": "--db test --port 9999 --debug --ttl 00:01:00"
+ }
+ }
+}
+```
+
+---
+
+## Краевые случаи
+
+| Ввод в CLI | Ключ в словаре | Значение |
+|-----------|---------------|---------|
+| `--flag` (без значения) | `"flag"` | `"true"` |
+| `--flag=` (пустое) | `"flag"` | `""` |
+| `--flag "quoted value"` | `"flag"` | `"quoted value"` |
+| `-short=value` | `"short"` | `"value"` |
+| Неизвестный формат | Игнорируется молча | — |
diff --git a/src/Sa.Configuration/CommandLine/Readme.md b/src/Sa.Configuration/CommandLine/Readme.md
index 8a497924..57ce9998 100644
--- a/src/Sa.Configuration/CommandLine/Readme.md
+++ b/src/Sa.Configuration/CommandLine/Readme.md
@@ -1,68 +1,208 @@
-# Arguments Class
+# Arguments — Command-Line Parsing
-The `Arguments` class provides a robust way to parse command-line arguments, making it easier to manage application configurations. It handles various parameter formats and provides helper methods for different data types.
+Parse and consume command-line arguments in .NET apps with a simple dictionary-like API. Supports `--flag=value`, `--flag value`, short options (`-x`), and typed getters.
-## Features
+> **Key detail:** the parser strips leading dashes from parameter names. When you access a value, use the key **without** leading `-` or `--`.
+> Example: `--config_db` in CLI → `args["config_db"]` in code. `-v` in CLI → `args["v"]` in code.
-- Parse command-line arguments with support for various formats
-- Access parameters by name using indexer syntax
-- Helper methods for common data types (bool, int, float, long, TimeSpan)
-- Support for both `--param=value` and `--param value` formats
-- Support for short options like `-ip_override=127.0.0.1`
+## Quick Start
-## Usage
-
-### Basic Usage
+```csharp
+using Sa.Configuration.CommandLine;
+
+// Parse args (defaults to Environment.GetCommandLineArgs())
+var args = new Arguments(args);
+
+// Indexer access (returns null if absent) — keys have leading dashes stripped
+string? db = args["config_db"];
+string? file = args["config_file"];
+bool debug = args.IsPresent("debug"); // true if flag present & truthy
+
+// Typed helpers (return nullable, null on missing/invalid)
+int? port = args.GetInt("port");
+float? timeout = args.GetFloat("timeout");
+long offset = args.GetLong("offset");
+TimeSpan ttl = args.GetTimeSpan("ttl");
+bool verbose = args.GetBool("v"); // "true"/"1"/"yes"/"on" → true
+```
-To use the Arguments class, create an instance and access parameters using the indexer syntax:
+### Minimal Console App
```csharp
-// Create an instance of the Arguments class, passing the command-line arguments
+using Sa.Configuration.CommandLine;
+
var arguments = new Arguments(args);
-// Retrieve values for specific parameters
-string? configDb = arguments["--config_db"];
-string? configFile = arguments["--config_file"];
-string? configNLog = arguments["--config_nlog"];
-string? ipOverride = arguments["-ip_override"];
+Console.WriteLine($"DB: {arguments["db"] ?? "(default)"}");
+Console.WriteLine($"Port: {arguments.GetInt("port") ?? 5432}");
+Console.WriteLine($"Debug: {arguments.IsPresent("debug")}");
+Console.WriteLine($"TTL: {arguments.GetTimeSpan("ttl") ?? TimeSpan.Zero}");
+```
+
+Run:
+
+```bash
+dotnet run -- --db mydb --port 9999 --debug --ttl 00:05:00 -v
+```
+
+Output:
-// Display the retrieved values
-Console.WriteLine("Configuration Database: " + (configDb ?? "Not provided"));
-Console.WriteLine("Configuration File: " + (configFile ?? "Not provided"));
-Console.WriteLine("NLog Configuration: " + (configNLog ?? "Not provided"));
-Console.WriteLine("IP Override: " + (ipOverride ?? "Not provided"));
```
+DB: mydb
+Port: 9999
+Debug: True
+TTL: 00:05:00
+```
+
+---
+
+## Supported Formats
+
+| Format | CLI Input | Dictionary Key | Value |
+|--------|-----------|---------------|-------|
+| Long flag + space | `--key value` | `"key"` | `"value"` |
+| Equals sign | `--key=value` | `"key"` | `"value"` |
+| Short flag + space | `-k value` | `"k"` | `"value"` |
+| Short equals | `-k=v` | `"k"` | `"v"` |
+| Boolean flag | `--debug` | `"debug"` | `"true"` |
+| Quoted value | `--name "hello world"` | `"name"` | `"hello world"` |
-### Advanced Usage
+---
-The class also provides helper methods for different data types:
+## API Reference
+
+### Constructor
```csharp
-// Check if a parameter exists
-if (arguments.Contains("--config_db"))
-{
- // Get parameter as boolean
- bool? nosjmp = arguments.GetBool("-nosjmp");
+public Arguments(params IReadOnlyList args)
+```
- // Get parameter as integer
- int? port = arguments.GetInt("--port");
+Creates an instance from a list of argument strings.
- // Get parameter as float
- float? timeout = arguments.GetFloat("--timeout");
+### Static Factory
- // Get parameter as TimeSpan
- TimeSpan? duration = arguments.GetTimeSpan("--duration");
-}
+```csharp
+public static Arguments CreateDefault(string[]? args = null)
+```
+
+Shortcut that uses `Environment.GetCommandLineArgs()` when `args` is null.
+
+```csharp
+var args = Arguments.CreateDefault(); // reads Process.GetCurrentProcess().CommandLine
+```
+
+### Indexer
+
+```csharp
+public string? this[string param] { get; }
+```
+
+Returns the value for a parameter name, or `null` if not found. Keys are stored without leading dashes.
+
+```csharp
+var db = args["database"]; // null if --database was never passed
+```
+
+### Contains / IsPresent
+
+```csharp
+public bool Contains(string param) // true if key exists (even if value is empty)
+public bool IsPresent(string param) // true if key exists AND value is non-null
```
+`IsPresent` distinguishes between a missing flag and a present-but-empty flag.
+
+### Typed Getters
+
+All return `T?` (nullable) and yield `null` when the parameter is absent or unparsable.
+
+| Method | Return Type | Example |
+|--------|-------------|---------|
+| `GetBool(string)` | `bool?` | `args.GetBool("verbose")` — accepts `true/1/yes/on` |
+| `GetInt(string)` | `int?` | `args.GetInt("port")` |
+| `GetFloat(string)`| `float?`| `args.GetFloat("ratio")` |
+| `GetLong(string)` | `long?` | `args.GetLong("offset")` |
+| `GetTimeSpan(string)` | `TimeSpan?` | `args.GetTimeSpan("delay")` |
+
+All numeric parsing uses `CultureInfo.InvariantCulture`.
+
+### Raw Parameters
+
+```csharp
+public IReadOnlyDictionary Parameters { get; }
+```
+
+Returns the full dictionary of parsed parameters. Keys are stored without leading dashes.
+
+---
+
+## Integration with Microsoft.Extensions.Configuration
+
+Register command-line arguments as an `IConfiguration` source:
+
+```csharp
+using Microsoft.Extensions.Configuration;
+using Sa.Configuration.CommandLine;
+
+var configuration = new ConfigurationBuilder()
+ .AddSaCommandLine(args) // <-- adds CLI args as config source
+ .AddJsonFile("appsettings.json", optional: true)
+ .Build();
+
+// Access via IConfiguration indexer — keys still have dashes stripped
+var db = configuration["db"];
+var port = configuration["port"];
+```
+
+Order matters: sources registered **later** override earlier ones. Place `AddSaCommandLine` before JSON/file sources if you want CLI to win:
+
+```csharp
+new ConfigurationBuilder()
+ .AddJsonFile("appsettings.json") // base defaults
+ .AddSaCommandLine(args) // overrides from CLI
+ .Build();
+```
+
+---
+
## Running the Application
-To run the application with command-line arguments, you can use the command line or terminal. Here are examples:
+### From terminal
```bash
-# Standard usage
-dotnet run Some.exe --config_db /opt/service_configs/config_db.json --config_file /opt/service_configs/appsettings.json --config_nlog /opt/service_configs/NLog.config -ip_override=127.0.0.1 -nosjmp
+# Long flags with space separator
+dotnet run --project MyApp.dll --db production --port 5432 --debug
+
+# Equals syntax
+dotnet run --project MyApp.dll --db=production --port=5432
+
+# Mixed formats
+dotnet run -- -d --db=prod -p 3306 --ttl 30s
+```
+
+### From Visual Studio / VS Code
+
+Set arguments in launchSettings.json:
+
+```json
+{
+ "profiles": {
+ "MyApp": {
+ "commandName": "Project",
+ "commandLineArgs": "--db test --port 9999 --debug --ttl 00:01:00"
+ }
+ }
+}
+```
+
+---
+
+## Edge Cases
-# Alternative format
-dotnet run Some.exe --config_db=/opt/service_configs/config_db.json --config_file=/opt/service_configs/appsettings.json --config_nlog=/opt/service_configs/NLog.config -ip_override="127.0.0.1" -nosjmp
-```
\ No newline at end of file
+| CLI Input | Dictionary Key | Value |
+|-----------|---------------|-------|
+| `--flag` (no value) | `"flag"` | `"true"` |
+| `--flag=` (empty) | `"flag"` | `""` |
+| `--flag "quoted value"` | `"flag"` | `"quoted value"` |
+| `-short=value` | `"short"` | `"value"` |
+| Unknown format | Ignored silently | — |
diff --git a/src/Sa.Configuration/Readme-ru.md b/src/Sa.Configuration/Readme-ru.md
new file mode 100644
index 00000000..af5f7f3e
--- /dev/null
+++ b/src/Sa.Configuration/Readme-ru.md
@@ -0,0 +1,284 @@
+# Sa.Configuration
+
+Безопасное управление секретами и парсер командной строки в экосистеме .NET `Microsoft.Extensions.Configuration`. Секреты автоматически подставляются в конфигурацию без ручного кода приложения.
+
+---
+
+## Возможности
+
+- **Автоматическая подстановка секретов**: плейсхолдеры `{{key}}` заменяются реальными значениями из файлов, переменных окружения или аргументов командной строки
+- **Защита от циклов**: встроенная защита от бесконечной рекурсии при разрешении плейсхолдеров
+- **Опциональные плейсхолдеры**: `{{?key}}` — если секрет не найден, возвращается `null` вместо исключения
+- **Цепочка хранилищ**: несколько источников секретов с приоритетным порядком
+- **Парсер аргументов**: поддерживает форматы `--key value`, `--key=value`, `-flag`
+- **Среды разработки**: автоматическая загрузка `secrets.{Environment}.txt` (Development/Staging/Production)
+
+---
+
+## Быстрый старт
+
+### 1. Регистрация в `Program.cs`
+
+```csharp
+using Sa.Configuration;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Подключение аргументов + секретов из файлов/ENV/CLI
+builder.Configuration.AddSaConfiguration();
+
+var app = builder.Build();
+```
+
+### 2. Файл секретов (`secrets.txt`)
+
+```ini
+# Postgres
+sa_pg_host=localhost
+sa_pg_user=postgres
+sa_pg_port=5432
+sa_pg_database=myapp
+sa_pg_schema=public
+sa_pg_password=superSecret123
+
+# API ключи
+api_key=abc123xyz
+jwt_secret=h8k2m9p0
+```
+
+> ⚠️ Добавьте `secrets*.txt` в `.gitignore`!
+
+### 3. Плейсхолдеры в `appsettings.json`
+
+```json
+{
+ "secret": "{{sa_secret}}",
+
+ "sa": {
+ "pg": {
+ "connection": "User ID={{sa_pg_user}};Password={{sa_pg_password}};Host={{sa_pg_host}};Port={{sa_pg_port}};Database={{sa_pg_database}};Pooling=true;SearchPath={{sa_pg_schema}};Command Timeout=180;"
+ }
+ },
+
+ "ExternalApi": {
+ "ApiKey": "{{api_key}}"
+ }
+}
+```
+
+### 4. Чтение конфигурации
+
+```csharp
+var pgConn = app.Configuration["sa:pg:connection"];
+// → "User ID=postgres;Password=superSecret123;Host=localhost;..."
+```
+
+---
+
+## Приоритет секретов
+
+Секреты ищутся в порядке убывания приоритета:
+
+| # | Источник | Пример файла |
+|---|----------|-------------|
+| 1 | Базовый файл секретов | `secrets.txt` |
+| 2 | Файл конкретной среды | `secrets.Development.txt` |
+| 3 | Переменные окружения | `SA_PG_PASSWORD=...` |
+| 4 | Аргументы командной строки | `--sa_pg_password=...` |
+
+Первый источник, имеющий значение, побеждает. Это позволяет переопределять секреты для каждой среды.
+
+---
+
+## Опциональные плейсхолдеры
+
+Используйте `{{?key}}` вместо `{{key}}`, чтобы избежать ошибки при отсутствии секрета:
+
+```json
+{
+ "optional_feature": "{{?feature_flag}}"
+}
+```
+
+Если `feature_flag` не найден ни в одном хранилище, возвращается `null`.
+
+---
+
+## Использование с Sa.Configuration.PostgreSql
+
+```csharp
+using Sa.Configuration;
+using Sa.Configuration.PostgreSql;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Сначала стандартные источники (appsettings.json, secrets.txt)
+builder.Configuration.AddSaConfiguration();
+
+// Затем динамические настройки из базы данных
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ ConnectionString: "...",
+ SelectSql: "SELECT key, value FROM app_settings"
+));
+
+var app = builder.Build();
+```
+
+---
+
+## Аргументы — Парсер командной строки
+
+```csharp
+using Sa.Configuration.CommandLine;
+
+// some.exe --config_db /share/data.db --debug
+var args = new Arguments(args);
+
+string? configDb = args["config_db"]; // → "/share/data.db"
+bool? debug = args.GetBool("debug"); // → true
+int? port = args.GetInt("port"); // → null
+TimeSpan? timeout = args.GetTimeSpan("timeout");
+```
+
+Поддерживаемые форматы:
+
+```
+--key value
+--key=value
+-key value
+-key=value
+-flag → flag=true (булев флаг)
+```
+
+Типизированные методы возвращают `null`, когда параметр отсутствует или невалиден:
+
+| Метод | Возвращаемый тип | Преобразование |
+|-------|-----------------|----------------|
+| `GetBool()` | `bool?` | `"true"/"1"/"yes"/"on"` → `true` |
+| `GetInt()` | `int?` | `int.TryParse(..., InvariantCulture)` |
+| `GetFloat()` | `float?` | то же самое |
+| `GetLong()` | `long?` | то же самое |
+| `GetTimeSpan()` | `TimeSpan?` | `TimeSpan.TryParse(..., InvariantCulture)` |
+
+Дополнительные методы:
+
+| Метод | Возвращаемый тип | Описание |
+|-------|-----------------|---------|
+| `Contains(param)` | `bool` | Проверяет наличие параметра |
+| `IsPresent(param)` | `bool` | Параметр существует И имеет непустое значение |
+
+---
+
+## Секреты — Управление секретами
+
+### Создание по умолчанию
+
+```csharp
+using Sa.Configuration.SecretStore;
+
+// Стандартная цепочка: File → File.Env → EnvVar → CommandLine
+var secrets = Secrets.CreateDefault();
+```
+
+### Пользовательская цепочка
+
+```csharp
+var secrets = new Secrets(
+ new FileSecretStore("my-secrets.txt"),
+ new EnvironmentVariableSecretStore(),
+ new InMemorySecretStore(new Dictionary {
+ { "override_key", "override_value" }
+ })
+);
+```
+
+### Добавление на лету
+
+```csharp
+secrets.AddStore(new FileSecretStore("additional-secrets.txt"));
+```
+
+### Подстановка плейсхолдеров
+
+```csharp
+string template = "Server={{host}};Password={{password}}";
+string result = secrets.PopulateSecrets(template);
+// → "Server=localhost;Password=s3cret!"
+```
+
+### Получение одного секрета
+
+```csharp
+string? password = secrets.GetSecret("sa_pg_password");
+```
+
+### Определение имени среды
+
+```csharp
+string env = Secrets.GetEnvironmentName();
+// → "Development", "Staging", "Production" и т.д.
+```
+
+---
+
+## Публичный API
+
+### Пространство имён `Sa.Configuration`
+
+| Тип | Назначение |
+|-----|-----------|
+| `Setup.AddSaConfiguration()` | Главная точка входа: подключение аргументов + обработка секретов |
+
+### Пространство имён `Sa.Configuration.CommandLine`
+
+| Тип | Назначение |
+|-----|-----------|
+| `Arguments` | Парсер аргументов командной строки |
+| `Arguments.CreateDefault()` | Создаёт из `Environment.GetCommandLineArgs()` |
+| `Setup.AddSaCommandLine()` | Метод-расширение для `IConfigurationBuilder` |
+
+### Пространство имён `Sa.Configuration.SecretStore`
+
+| Тип | Назначение |
+|-----|-----------|
+| `Secrets` | Основной класс управления секретами, реализует `ISecretService` |
+| `Secrets.CreateDefault()` | Стандартная цепочка хранилищ |
+| `Secrets.GetEnvironmentName()` | Определяет среду (`DOTNET_ENVIRONMENT` / `ASPNETCORE_ENVIRONMENT`) |
+| `SecretOptions` | Опции для `CreateDefault()`: `FileName`, `Args`, `EnvironmentName` |
+| `ISecretService` | Интерфейс: `PopulateSecrets()` + `GetSecret()` |
+| `ISecretStore` | Интерфейс: `GetSecret(string key)` |
+| `Setup.AddSaPostSecretProcessing()` | Метод-расширение: применяет `ISecretService` к конфигу ПОСЛЕ загрузки других источников |
+
+### Хранилища секретов (`Sa.Configuration.SecretStore.Stories`)
+
+| Класс | Описание |
+|-------|---------|
+| `FileSecretStore` | Загружает `key=value` из текстового файла (пропускает комментарии `#`) |
+| `EnvironmentVariableSecretStore` | Читает из `Environment.GetEnvironmentVariable()` |
+| `CommandLineArgsSecretStore` | Берёт секреты из `Arguments` |
+| `InMemorySecretStore` | Словарь в памяти, fluent `.AddSecret()` |
+
+---
+
+## Как это работает
+
+```
+┌──────────────────────────────────────────────────────┐
+│ 1. appsettings.json содержит: │
+│ "connection": "Host={{sa_pg_host}};Password={{...}}"│
+├──────────────────────────────────────────────────────┤
+│ 2. secrets.txt содержит: │
+│ sa_pg_host=localhost │
+│ sa_pg_password=s3cret! │
+├──────────────────────────────────────────────────────┤
+│ 3. AddSaPostSecretProcessing подставляет плейсхолдеры:│
+│ IConfiguration["sa:pg:connection"] │
+│ → "Host=localhost;Password=s3cret!;..." │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.Configuration/Readme.md b/src/Sa.Configuration/Readme.md
index 880ac51d..bef68115 100644
--- a/src/Sa.Configuration/Readme.md
+++ b/src/Sa.Configuration/Readme.md
@@ -1,168 +1,284 @@
-# Working with Secrets via Configuration
+# Sa.Configuration
-The `Sa.Configuration` library provides **secure and transparent integration of secrets** into the standard .NET configuration system. All sensitive data is automatically substituted during configuration loading — without manual processing in application code.
+Secure secrets management and command-line argument parsing within the .NET `Microsoft.Extensions.Configuration` ecosystem. Secrets are automatically substituted into configuration without manual application code.
---
-## How It Works
+## Features
-1. **Load secrets** from secure sources (files, environment variables)
-2. **Automatic substitution** of values in configuration during loading
-3. **Transparent usage** via standard `IConfiguration`
+- **Automatic secret substitution**: `{{key}}` placeholders are replaced with real values from files, environment variables, or command-line arguments
+- **Cycle protection**: built-in guard against infinite recursion during placeholder resolution
+- **Optional placeholders**: `{{?key}}` — if the secret is not found, returns `null` instead of throwing
+- **Chained Stores**: multiple secret sources with priority ordering
+- **Argument parser**: supports `--key value`, `--key=value`, `-flag` formats
+- **Environments**: automatic loading of `secrets.{Environment}.txt` (Development/Staging/Production)
---
-## Setup
+## Quick Start
-### 1. Registration in `Program.cs`
+### 1. Register in `Program.cs`
```csharp
using Sa.Configuration;
var builder = WebApplication.CreateBuilder(args);
+// Connects arguments + secrets from files/env vars/command line
builder.Configuration.AddSaConfiguration();
var app = builder.Build();
```
-### 2. Secret Sources
-
-Secrets are loaded from the following sources (in priority order):
-
-| Source | Description | Example |
-|--------|-------------|---------|
-| **Secrets file** | Text file with `key=value` pairs | `secrets.txt` |
-| **Environment variables** | System environment variables | `SA_PG_PASSWORD=myPass` |
-| **Command-line arguments** | Application startup parameters | `--sa_pg_port=5432` |
-
----
-
-## Secrets File Format (`secrets.txt`)
+### 2. Secrets File (`secrets.txt`)
```ini
# Postgres
sa_pg_host=localhost
sa_pg_user=postgres
sa_pg_port=5432
-sa_pg_database=postgres
+sa_pg_database=myapp
sa_pg_schema=public
sa_pg_password=superSecret123
-# Other secrets
-sa_secret=TOP SECRET!
+# API keys
api_key=abc123xyz
+jwt_secret=h8k2m9p0
```
-> ⚠️ **Important**: The `secrets.txt` file must be excluded from version control (.gitignore)
-
----
+> ⚠️ Add `secrets*.txt` to `.gitignore`!
-## Usage in `appsettings.json`
-
-Specify **placeholders** in the format `{{secret_key}}`:
+### 3. Placeholders in `appsettings.json`
```json
{
"secret": "{{sa_secret}}",
-
+
"sa": {
"pg": {
"connection": "User ID={{sa_pg_user}};Password={{sa_pg_password}};Host={{sa_pg_host}};Port={{sa_pg_port}};Database={{sa_pg_database}};Pooling=true;SearchPath={{sa_pg_schema}};Command Timeout=180;"
}
},
-
+
"ExternalApi": {
"ApiKey": "{{api_key}}"
}
}
```
+### 4. Reading Configuration
+
+```csharp
+var pgConn = app.Configuration["sa:pg:connection"];
+// → "User ID=postgres;Password=superSecret123;Host=localhost;..."
+```
+
---
-## Code Example
+## Secret Priority Order
-### Retrieving values via `IConfiguration`
+Secrets are looked up in descending priority order:
-```csharp
-var todosApi = app.MapGroup("/settings");
+| # | Source | Example File |
+|---|--------|-------------|
+| 1 | Base secrets file | `secrets.txt` |
+| 2 | Environment-specific file | `secrets.Development.txt` |
+| 3 | Environment variables | `SA_PG_PASSWORD=...` |
+| 4 | Command-line arguments | `--sa_pg_password=...` |
+
+The first source that has a value wins. This allows overriding secrets per environment.
+
+---
+
+## Optional Placeholders
-todosApi.MapGet("/", (IConfiguration configuration) => new Settings[] {
- new (Key: "pg_connection", Value: configuration["sa:pg:connection"]),
- new (Key: "theme", Value: configuration["theme"]),
- new (Key: "secret", Value: configuration["secret"])
-}).WithName("GetSettings");
+Use `{{?key}}` instead of `{{key}}` to avoid an error when a secret is missing:
+
+```json
+{
+ "optional_feature": "{{?feature_flag}}"
+}
```
+If `feature_flag` is not found in any store, `null` is returned.
---
-## What Happens Under the Hood
+## Usage with Sa.Configuration.PostgreSql
-```
-┌─────────────────────────────────────────────────────────┐
-│ 1. appsettings.json contains: │
-│ "connection": "Host={{sa_pg_host}};Password={{...}}" │
-├─────────────────────────────────────────────────────────┤
-│ 2. secrets.txt contains: │
-│ sa_pg_host=localhost │
-│ sa_pg_password=superSecret123 │
-├─────────────────────────────────────────────────────────┤
-│ 3. IConfiguration["sa:pg:connection"] returns: │
-│ "Host=localhost;Password=superSecret123;..." │
-└─────────────────────────────────────────────────────────┘
+```csharp
+using Sa.Configuration;
+using Sa.Configuration.PostgreSql;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// First, standard sources (appsettings.json, secrets.txt)
+builder.Configuration.AddSaConfiguration();
+
+// Then, dynamic settings from the database
+builder.Configuration.AddSaPostgreSqlConfiguration(new PostgreSqlConfigurationOptions(
+ ConnectionString: "...",
+ SelectSql: "SELECT key, value FROM app_settings"
+));
+
+var app = builder.Build();
```
---
-## Advantages
+## Arguments — Command-Line Argument Parser
+
+```csharp
+using Sa.Configuration.CommandLine;
-- **Security**: secrets are not stored in code or configuration files
-- **Flexibility**: supports multiple secret sources
-- **Simplicity**: transparent operation through standard `IConfiguration`
-- **Debugging**: easy to switch secrets via environment variables or arguments
+// some.exe --config_db /share/data.db --debug
+var args = new Arguments(args);
----
+string? configDb = args["config_db"]; // → "/share/data.db"
+bool? debug = args.GetBool("debug"); // → true
+int? port = args.GetInt("port"); // → null
+TimeSpan? timeout = args.GetTimeSpan("timeout");
+```
-## Tips
+Supported formats:
-- For local development, create `secrets.Development.txt`; for production — use environment variables
-- Never commit secret files to the repository
-- Use different secret files for different environments (dev, staging, prod)
+```
+--key value
+--key=value
+-key value
+-key=value
+-flag → flag=true (boolean flag)
+```
+
+Typed methods return `null` when the parameter is absent or invalid:
+
+| Method | Return Type | Conversion |
+|--------|------------|------------|
+| `GetBool()` | `bool?` | `"true"/"1"/"yes"/"on"` → `true` |
+| `GetInt()` | `int?` | `int.TryParse(..., InvariantCulture)` |
+| `GetFloat()` | `float?` | same as above |
+| `GetLong()` | `long?` | same as above |
+| `GetTimeSpan()` | `TimeSpan?` | `TimeSpan.TryParse(..., InvariantCulture)` |
+
+Additional methods:
+
+| Method | Return Type | Description |
+|--------|------------|-------------|
+| `Contains(param)` | `bool` | Checks if parameter exists |
+| `IsPresent(param)` | `bool` | Parameter exists AND has a non-null value |
---
-# Core Classes
+## Secrets — Secrets Management
+
+### Creating Defaults
-## Arguments Class
+```csharp
+using Sa.Configuration.SecretStore;
-The `Arguments` class is designed to parse command-line arguments passed to a C# application. It provides a dictionary-like interface for easy parameter retrieval and supports both single-value and multi-value parameters.
+// Standard chain: File → File.Env → EnvVar → CommandLine
+var secrets = Secrets.CreateDefault();
+```
-**Key Features:**
-- **Parameter Parsing**: Splits command-line arguments into key-value pairs
-- **Easy Retrieval**: Access parameter values using an indexer
-- **Default Handling**: Automatically assigns default values for boolean flags
+### Custom Chain
-**Example:**
```csharp
-// some.exe --config_db /share/data.db
-var arguments = new Arguments(args);
-string? configDb = arguments["config_db"];
+var secrets = new Secrets(
+ new FileSecretStore("my-secrets.txt"),
+ new EnvironmentVariableSecretStore(),
+ new InMemorySecretStore(new Dictionary {
+ { "override_key", "override_value" }
+ })
+);
```
----
+### Fluent Addition at Runtime
+
+```csharp
+secrets.AddStore(new FileSecretStore("additional-secrets.txt"));
+```
+
+### Placeholder Substitution
+
+```csharp
+string template = "Server={{host}};Password={{password}}";
+string result = secrets.PopulateSecrets(template);
+// → "Server=localhost;Password=s3cret!"
+```
-## Secrets Class
+### Getting a Single Secret
-The `Secrets` class provides a secure mechanism for managing sensitive information such as API keys and database passwords from various sources. It supports loading secrets from files, environment variables, and dynamically generated host key files.
+```csharp
+string? password = secrets.GetSecret("sa_pg_password");
+```
-**Key Features:**
-- **Chained Secret Stores**: Combines multiple sources for retrieving secrets
-- **Dynamic Loading**: Supports environment-specific configurations
-- **Placeholder Replacement**: Easily populates strings with secret values
+### Environment Name Resolution
-**Example:**
```csharp
-string input = "Database password: {{db_password}}";
-string? populatedString = service.PopulateSecrets(input);
+string env = Secrets.GetEnvironmentName();
+// → "Development", "Staging", "Production", etc.
```
+
+---
+
+## Public API
+
+### Namespace `Sa.Configuration`
+
+| Type | Purpose |
+|------|---------|
+| `Setup.AddSaConfiguration()` | Main entry-point: connects arguments + secret processing |
+
+### Namespace `Sa.Configuration.CommandLine`
+
+| Type | Purpose |
+|------|---------|
+| `Arguments` | Command-line argument parser |
+| `Arguments.CreateDefault()` | Creates from `Environment.GetCommandLineArgs()` |
+| `Setup.AddSaCommandLine()` | Extension method for `IConfigurationBuilder` |
+
+### Namespace `Sa.Configuration.SecretStore`
+
+| Type | Purpose |
+|------|---------|
+| `Secrets` | Main secrets management class, implements `ISecretService` |
+| `Secrets.CreateDefault()` | Standard store chain |
+| `Secrets.GetEnvironmentName()` | Resolves environment (`DOTNET_ENVIRONMENT` / `ASPNETCORE_ENVIRONMENT`) |
+| `SecretOptions` | Options for `CreateDefault()`: `FileName`, `Args`, `EnvironmentName` |
+| `ISecretService` | Interface: `PopulateSecrets()` + `GetSecret()` |
+| `ISecretStore` | Interface: `GetSecret(string key)` |
+| `Setup.AddSaPostSecretProcessing()` | Extension method: applies `ISecretService` to config AFTER other sources are loaded |
+
+### Secret Stores (`Sa.Configuration.SecretStore.Stories`)
+
+| Class | Description |
+|-------|-------------|
+| `FileSecretStore` | Loads `key=value` from a text file (skips `#` comments) |
+| `EnvironmentVariableSecretStore` | Reads from `Environment.GetEnvironmentVariable()` |
+| `CommandLineArgsSecretStore` | Pulls secrets from `Arguments` |
+| `InMemorySecretStore` | Dictionary in memory, fluent `.AddSecret()` |
+
+---
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────┐
+│ 1. appsettings.json contains: │
+│ "connection": "Host={{sa_pg_host}};Password={{...}}"│
+├──────────────────────────────────────────────────────┤
+│ 2. secrets.txt contains: │
+│ sa_pg_host=localhost │
+│ sa_pg_password=s3cret! │
+├──────────────────────────────────────────────────────┤
+│ 3. AddSaPostSecretProcessing substitutes placeholders:│
+│ IConfiguration["sa:pg:connection"] │
+│ → "Host=localhost;Password=s3cret!;..." │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## License
+
+MIT
diff --git a/src/Sa.Configuration/Sa.Configuration.csproj b/src/Sa.Configuration/Sa.Configuration.csproj
index 6041109a..4258918b 100644
--- a/src/Sa.Configuration/Sa.Configuration.csproj
+++ b/src/Sa.Configuration/Sa.Configuration.csproj
@@ -3,7 +3,7 @@
- 0.9.1
+ 0.10.0
extensions for Configuration
diff --git a/src/Sa.Configuration/SecretStore/Engine/SecretService.cs b/src/Sa.Configuration/SecretStore/Engine/SecretService.cs
index db545376..058e3459 100644
--- a/src/Sa.Configuration/SecretStore/Engine/SecretService.cs
+++ b/src/Sa.Configuration/SecretStore/Engine/SecretService.cs
@@ -69,7 +69,7 @@ internal sealed partial class SecretService(ISecretStore secretStore) : ISecretS
}
private static bool IsSearchPositionValid(string inputString, int currentPosition)
- => inputString.Length >= currentPosition;
+ => currentPosition < inputString.Length;
private static string NormalizeValue(string secretValue)
{
diff --git a/src/Sa.Data.PostgreSql/DbCommandExtensions.cs b/src/Sa.Data.PostgreSql/DbCommandExtensions.cs
index cf1e0731..ee5ed1fb 100644
--- a/src/Sa.Data.PostgreSql/DbCommandExtensions.cs
+++ b/src/Sa.Data.PostgreSql/DbCommandExtensions.cs
@@ -7,7 +7,7 @@ namespace Sa.Data.PostgreSql;
public static class DbCommandExtensions
{
///
- /// Добавляет параметр с именем {prefix}{index}, используя минимальные аллокации.
+ /// Adds a parameter with name {prefix}{index}, using minimal allocations.
///
public static NpgsqlCommand AddParameter(
this NpgsqlCommand command,
@@ -26,17 +26,22 @@ public static NpgsqlCommand AddParameter(
return command;
}
-
+ ///
+ /// Adds a parameter — infers the value type from the argument.
+ ///
public static NpgsqlCommand AddParam(
this NpgsqlCommand command,
string prefix,
- T value,
+ T? value,
int index)
where TProvider : INamePrefixProvider
{
var paramName = CachedParamNames.Default.Get(prefix, index);
- var param = new NpgsqlParameter(paramName, value);
+ var param = command.CreateParameter();
+ param.ParameterName = paramName;
+ param.Value = value is null ? DBNull.Value : (object)value!;
command.Parameters.Add(param);
+
return command;
}
}
diff --git a/src/Sa.Data.PostgreSql/IPgDataSource.cs b/src/Sa.Data.PostgreSql/IPgDataSource.cs
index 11978fc2..63deb9ce 100644
--- a/src/Sa.Data.PostgreSql/IPgDataSource.cs
+++ b/src/Sa.Data.PostgreSql/IPgDataSource.cs
@@ -28,9 +28,72 @@ Task ExecuteNonQuery(string sql, CancellationToken cancellationToken = defa
Task ExecuteScalar(
string sql, Action? initCommand, CancellationToken cancellationToken = default);
+ ///
+ /// Executes a scalar query with no parameters.
+ ///
+ Task ExecuteScalar(string sql, CancellationToken cancellationToken = default)
+ => ExecuteScalar(sql, null, cancellationToken);
+
+
async Task ExecuteScalar(
string sql, Action? initCommand, CancellationToken cancellationToken = default)
- => ((T)(await ExecuteScalar(sql, initCommand, cancellationToken))!);
+ {
+ var result = await ExecuteScalar(sql, initCommand, cancellationToken).ConfigureAwait(false);
+ return (T)(result!);
+ }
+
+
+ ///
+ /// Executes a typed scalar query.
+ ///
+ async Task ExecuteScalarTyped(
+ string sql, Action? initCommand = null, CancellationToken cancellationToken = default)
+ {
+ var result = await ExecuteScalar(sql, initCommand, cancellationToken).ConfigureAwait(false);
+ if (result is null || result is DBNull)
+ return default!;
+
+ var targetType = typeof(T);
+
+ // Handle value types that Npgsql returns boxed
+ if (result is T typed)
+ return typed;
+
+ // Direct cast for common types that may not match 'is T' due to nullable annotations
+ if (targetType == typeof(Guid) && result is Guid g)
+ return (T)(object)g;
+ if (targetType == typeof(DateTime) && result is DateTime dt)
+ return (T)(object)dt;
+ if (targetType == typeof(DateTimeOffset) && result is DateTimeOffset dto)
+ return (T)(object)dto;
+
+ // DateOnly -> DateTime conversion (PostgreSQL 'date' type maps to DateOnly in .NET 6+)
+ if (targetType == typeof(DateTime) && result is DateOnly dateOnly)
+ return (T)(object)dateOnly.ToDateTime(TimeOnly.MinValue);
+
+ // Fallback: use as-cast for reference/nullable types
+ if (result is T directCast)
+ return directCast;
+
+ return (T)Convert.ChangeType(result, typeof(T), null)!;
+ }
+
+ ///
+ /// Executes a typed scalar query with parameters.
+ ///
+ async Task ExecuteScalarTyped(
+ string sql,
+ IReadOnlyCollection parameters,
+ CancellationToken cancellationToken = default)
+ {
+ var result = await ExecuteScalar(sql, cmd => FillParams(cmd, parameters), cancellationToken).ConfigureAwait(false);
+ if (result is null || result is DBNull)
+ return default!;
+ if (result is T typed)
+ return typed;
+ return (T)Convert.ChangeType(result, typeof(T), null)!;
+ }
+
// ExecuteReader
Task ExecuteReader(
@@ -48,7 +111,7 @@ Task ExecuteReader(
async Task ExecuteReader(
string sql, Action read, CancellationToken cancellationToken = default)
- => await ExecuteReader(sql, read, [], cancellationToken);
+ => await ExecuteReader(sql, read, [], cancellationToken).ConfigureAwait(false);
// ExecuteReaderList
@@ -58,7 +121,7 @@ async Task> ExecuteReaderList(
string sql, Func read, CancellationToken cancellationToken = default)
{
List list = [];
- await ExecuteReader(sql, (reader, _) => list.Add(read(reader)), cancellationToken);
+ await ExecuteReader(sql, (reader, _) => list.Add(read(reader)), cancellationToken).ConfigureAwait(false);
return list;
}
@@ -69,7 +132,7 @@ async Task> ExecuteReaderList(
CancellationToken cancellationToken = default)
{
List list = [];
- await ExecuteReader(sql, (reader, _) => list.Add(read(reader)), parameters, cancellationToken);
+ await ExecuteReader(sql, (reader, _) => list.Add(read(reader)), parameters, cancellationToken).ConfigureAwait(false);
return list;
}
@@ -91,22 +154,28 @@ async Task ExecuteReaderFirst(
await ExecuteReader(sql, (reader, _) =>
{
- value = Type.GetTypeCode(typeof(T)) switch
+ value = typeof(T) switch
{
- TypeCode.Char => (T)(object)reader.GetChar(0),
- TypeCode.Int64 => (T)(object)reader.GetInt64(0),
- TypeCode.Int32 => (T)(object)reader.GetInt32(0),
- TypeCode.String => (T)(object)reader.GetString(0),
- TypeCode.Boolean => (T)(object)reader.GetBoolean(0),
- TypeCode.Double => (T)(object)reader.GetDouble(0),
- TypeCode.DateTime => (T)(object)reader.GetDateTime(0),
- TypeCode.Decimal => (T)(object)reader.GetDecimal(0),
- TypeCode.DBNull => value,
- _ => throw new InvalidOperationException($"Unsupported type: {typeof(T)}"),
+ Type t when t == typeof(Guid) => (T)(object)reader.GetFieldValue(0),
+ Type t when t == typeof(DateTimeOffset) => (T)(object)reader.GetFieldValue(0),
+ _ => Type.GetTypeCode(typeof(T)) switch
+ {
+ TypeCode.Char => (T)(object)reader.GetChar(0),
+ TypeCode.Int64 => (T)(object)reader.GetInt64(0),
+ TypeCode.Int32 => (T)(object)reader.GetInt32(0),
+ TypeCode.String => (T)(object)reader.GetString(0),
+ TypeCode.Boolean => (T)(object)reader.GetBoolean(0),
+ TypeCode.Double => (T)(object)reader.GetDouble(0),
+ TypeCode.DateTime => (T)(object)reader.GetDateTime(0),
+ TypeCode.Decimal => (T)(object)reader.GetDecimal(0),
+ TypeCode.Int16 => (T)(object)reader.GetInt16(0),
+ TypeCode.DBNull => value,
+ _ => throw new InvalidOperationException($"Unsupported type: {typeof(T)}"),
+ }
};
}
, parameters
- , cancellationToken);
+ , cancellationToken).ConfigureAwait(false);
return value;
}
diff --git a/src/Sa.Data.PostgreSql/IPgDistributedLock.cs b/src/Sa.Data.PostgreSql/IPgDistributedLock.cs
deleted file mode 100644
index 1d4eec50..00000000
--- a/src/Sa.Data.PostgreSql/IPgDistributedLock.cs
+++ /dev/null
@@ -1,9 +0,0 @@
-namespace Sa.Data.PostgreSql;
-
-public interface IPgDistributedLock
-{
- Task TryExecuteInDistributedLock(
- long lockId,
- Func exclusiveLockTask,
- CancellationToken cancellationToken);
-}
diff --git a/src/Sa.Data.PostgreSql/PgDataSource.cs b/src/Sa.Data.PostgreSql/PgDataSource.cs
index 40fe0980..f07a9592 100644
--- a/src/Sa.Data.PostgreSql/PgDataSource.cs
+++ b/src/Sa.Data.PostgreSql/PgDataSource.cs
@@ -1,4 +1,5 @@
using Npgsql;
+using System.Data;
namespace Sa.Data.PostgreSql;
@@ -28,7 +29,7 @@ public async ValueTask DisposeAsync()
{
if (_dataSource.IsValueCreated)
{
- await _dataSource.Value.DisposeAsync();
+ await _dataSource.Value.DisposeAsync().ConfigureAwait(false);
}
}
@@ -37,21 +38,41 @@ public async ValueTask BeginBinaryImport(
Func> write,
CancellationToken cancellationToken = default)
{
- using NpgsqlConnection db = await OpenDbConnection(cancellationToken);
- using NpgsqlBinaryImporter writer = await db.BeginBinaryImportAsync(sql, cancellationToken);
- ulong result = await write(writer, cancellationToken);
+ await using NpgsqlConnection db = await OpenDbConnection(cancellationToken).ConfigureAwait(false);
+ await using NpgsqlBinaryImporter writer = await db.BeginBinaryImportAsync(sql, cancellationToken).ConfigureAwait(false);
+ ulong result = await write(writer, cancellationToken).ConfigureAwait(false);
return result;
}
+ public async Task ExecuteTransactionAsync(
+ Func action,
+ IsolationLevel isolationLevel = IsolationLevel.Unspecified,
+ CancellationToken cancellationToken = default)
+ {
+ await using NpgsqlConnection connection = await OpenDbConnection(cancellationToken).ConfigureAwait(false);
+ await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
+ await using NpgsqlTransaction transaction = await connection.BeginTransactionAsync(isolationLevel, cancellationToken).ConfigureAwait(false);
+ try
+ {
+ await action(transaction, cancellationToken).ConfigureAwait(false);
+ await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
+ }
+ catch
+ {
+ await transaction.RollbackAsync(cancellationToken).ConfigureAwait(false);
+ throw;
+ }
+ }
+
public async Task ExecuteNonQuery(
string sql,
Action? initCommand,
CancellationToken cancellationToken = default)
{
- using NpgsqlConnection connection = await OpenDbConnection(cancellationToken);
- using NpgsqlCommand cmd = new(sql, connection);
+ await using NpgsqlConnection connection = await OpenDbConnection(cancellationToken).ConfigureAwait(false);
+ await using NpgsqlCommand cmd = new(sql, connection);
initCommand?.Invoke(cmd);
- return await cmd.ExecuteNonQueryAsync(cancellationToken);
+ return await cmd.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
}
public async Task ExecuteScalar(
@@ -59,10 +80,10 @@ public async Task ExecuteNonQuery(
Action? initCommand,
CancellationToken cancellationToken = default)
{
- using NpgsqlConnection connection = await OpenDbConnection(cancellationToken);
- using NpgsqlCommand cmd = new(sql, connection);
+ await using NpgsqlConnection connection = await OpenDbConnection(cancellationToken).ConfigureAwait(false);
+ await using NpgsqlCommand cmd = new(sql, connection);
initCommand?.Invoke(cmd);
- return await cmd.ExecuteScalarAsync(cancellationToken);
+ return await cmd.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
}
public async Task ExecuteReader(
@@ -73,11 +94,11 @@ public async Task ExecuteReader(
{
int rowCount = 0;
- using NpgsqlConnection connection = await OpenDbConnection(cancellationToken);
- using NpgsqlCommand cmd = new(sql, connection);
+ using NpgsqlConnection connection = await OpenDbConnection(cancellationToken).ConfigureAwait(false);
+ await using NpgsqlCommand cmd = new(sql, connection);
initCommand?.Invoke(cmd);
- using NpgsqlDataReader reader = await cmd.ExecuteReaderAsync(cancellationToken);
- while (await reader.ReadAsync(cancellationToken) && !cancellationToken.IsCancellationRequested)
+ await using NpgsqlDataReader reader = await cmd.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false);
+ while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false) && !cancellationToken.IsCancellationRequested)
{
read(reader, rowCount);
rowCount++;
diff --git a/src/Sa.Data.PostgreSql/PgDistributedLock.cs b/src/Sa.Data.PostgreSql/PgDistributedLock.cs
deleted file mode 100644
index 3b49dd87..00000000
--- a/src/Sa.Data.PostgreSql/PgDistributedLock.cs
+++ /dev/null
@@ -1,94 +0,0 @@
-using Microsoft.Extensions.Logging;
-using Microsoft.Extensions.Logging.Abstractions;
-using Npgsql;
-
-namespace Sa.Data.PostgreSql;
-
-///
-/// lock by pg_try_advisory_lock
-///
-///
-///
-internal sealed partial class PgDistributedLock(
- PgDataSourceSettings settings,
- ILogger? logger = null) : IPgDistributedLock
-{
- private readonly ILogger _logger = logger ?? NullLogger.Instance;
-
- private readonly NpgsqlConnectionStringBuilder builder = new(settings.ConnectionString);
-
- public async Task TryExecuteInDistributedLock(long lockId, Func exclusiveLockTask, CancellationToken cancellationToken)
- {
- LogTryingToAcquireLock(_logger, lockId);
-
- using var connection = new NpgsqlConnection(builder.ToString());
- await connection.OpenAsync(cancellationToken);
-
- bool hasLockedAcquired = await TryAcquireLockAsync(lockId, connection, cancellationToken);
-
- if (!hasLockedAcquired)
- {
- LogLockRejected(_logger, lockId);
- return false;
- }
-
- LogLockAcquired(_logger, lockId);
- try
- {
- if (await TryAcquireLockAsync(lockId, connection, cancellationToken))
- {
- await exclusiveLockTask(cancellationToken);
- }
- }
- finally
- {
- LogReleasingLock(_logger, lockId);
- await ReleaseLock(lockId, connection, cancellationToken);
- }
- return true;
- }
-
- private static async Task TryAcquireLockAsync(long lockId, NpgsqlConnection connection, CancellationToken cancellationToken)
- {
- string sessionLockCommand = $"SELECT pg_try_advisory_lock({lockId})";
- using var commandQuery = new NpgsqlCommand(sessionLockCommand, connection);
- object? result = await commandQuery.ExecuteScalarAsync(cancellationToken);
- if (result != null && bool.TryParse(result.ToString(), out var lockAcquired) && lockAcquired)
- {
- return true;
- }
- return false;
- }
-
- private static async Task ReleaseLock(long lockId, NpgsqlConnection connection, CancellationToken cancellationToke)
- {
- string transactionLockCommand = $"SELECT pg_advisory_unlock({lockId})";
- using var commandQuery = new NpgsqlCommand(transactionLockCommand, connection);
- await commandQuery.ExecuteScalarAsync(cancellationToke);
- }
-
-
- [LoggerMessage(
- EventId = 1001,
- Level = LogLevel.Trace,
- Message = "Trying to acquire session lock for Lock Id {LockId}")]
- static partial void LogTryingToAcquireLock(ILogger logger, long lockId);
-
- [LoggerMessage(
- EventId = 1002,
- Level = LogLevel.Information,
- Message = "Lock {LockId} rejected")]
- static partial void LogLockRejected(ILogger logger, long lockId);
-
- [LoggerMessage(
- EventId = 1003,
- Level = LogLevel.Information,
- Message = "Lock {LockId} acquired")]
- static partial void LogLockAcquired(ILogger logger, long lockId);
-
- [LoggerMessage(
- EventId = 1004,
- Level = LogLevel.Information,
- Message = "Releasing session lock for {LockId}")]
- static partial void LogReleasingLock(ILogger logger, long lockId);
-}
diff --git a/src/Sa.Data.PostgreSql/PgRetryStrategy.cs b/src/Sa.Data.PostgreSql/PgRetryStrategy.cs
index 1e36b9ac..aeb2653c 100644
--- a/src/Sa.Data.PostgreSql/PgRetryStrategy.cs
+++ b/src/Sa.Data.PostgreSql/PgRetryStrategy.cs
@@ -7,17 +7,17 @@ public static class PgRetryStrategy
public static ValueTask ExecuteWithRetry(
Func> fun,
int retryCount = 3,
- int initialDelay = 530,
+ int medianFirstRetryDelay = 530,
Func? next = null,
CancellationToken cancellationToken = default)
{
return Classes.Retry.Jitter(
fun: fun,
retryCount: retryCount,
- initialDelay: initialDelay
- , next: (ex, i) => next != null
+ medianFirstRetryDelay: medianFirstRetryDelay,
+ shouldRetry: (ex, i) => next != null
? next(ex, i)
- : (ex is NpgsqlException exception) && exception.IsTransient
- , cancellationToken: cancellationToken);
+ : (ex is NpgsqlException exception) && exception.IsTransient,
+ cancellationToken: cancellationToken);
}
}
diff --git a/src/Sa.Data.PostgreSql/Readme-ru.md b/src/Sa.Data.PostgreSql/Readme-ru.md
new file mode 100644
index 00000000..ff4be082
--- /dev/null
+++ b/src/Sa.Data.PostgreSql/Readme-ru.md
@@ -0,0 +1,188 @@
+# Sa.Data.PostgreSql
+
+Лёгкая обёртка над Npgsql для типичных операций с PostgreSQL — без ORM overhead, с поддержкой DI, AOT и минимальными аллокациями.
+
+---
+
+## Быстрый старт
+
+```csharp
+// Вариант 1: прямое создание
+var dataSource = IPgDataSource.Create("Host=db;Database=mydb;Username=usr;Password=pwd");
+
+// Вариант 2: через DI
+services.AddSaPostgreSqlDataSource(b => b.WithConnectionString("Host=db;Database=mydb;Username=usr;Password=pwd"));
+// или с factory (например, из IConfiguration):
+services.AddSaPostgreSqlDataSource(b => b.WithConnectionString(sp =>
+ sp.GetRequiredService().GetConnectionString("Default")));
+```
+
+---
+
+## ExecuteNonQuery
+
+Выполняет SQL-команду, которая не возвращает данные (INSERT / UPDATE / DELETE / DDL), и возвращает число затронутых строк.
+
+```csharp
+// Простой запрос
+int affected = await dataSource.ExecuteNonQuery("DELETE FROM sessions WHERE expired = true");
+
+// С параметрами
+int affected = await dataSource.ExecuteNonQuery("""
+ INSERT INTO users (name, age) VALUES (@p0, @p1);
+ """, [
+ new NpgsqlParameter { ParameterName = "p0", Value = "Tom" },
+ new NpgsqlParameter { ParameterName = "p1", Value = 18 }
+ ]);
+```
+
+---
+
+## ExecuteScalar / ExecuteScalarTyped
+
+Возвращает первое значение первой строки результата. `ExecuteScalarTyped` автоматически кастует результат, включая поддержку `Guid`, `DateTime`, `DateTimeOffset` и `DateOnly → DateTime`.
+
+```csharp
+// object? перегрузка
+object? count = await dataSource.ExecuteScalar("SELECT COUNT(*) FROM users");
+
+// Типизированная перегрузка
+int count = await dataSource.ExecuteScalarTyped("SELECT COUNT(*) FROM users");
+long id = await dataSource.ExecuteScalarTyped("SELECT nextval('users_id_seq')");
+Guid tenantId = await dataSource.ExecuteScalarTyped("SELECT tenant_uuid FROM tenants LIMIT 1");
+```
+
+---
+
+## ExecuteReader
+
+Потоковое чтение строк с callback'ом — идеально для обработки больших результатов без загрузки в память.
+
+```csharp
+int processed = 0;
+await dataSource.ExecuteReader("SELECT id, name FROM users", (reader, rowIndex) =>
+{
+ int id = reader.GetInt32(0);
+ string name = reader.GetString(1);
+ Console.WriteLine($"{rowIndex}: {id} → {name}");
+ processed++;
+});
+Console.WriteLine($"Processed {processed} rows");
+```
+
+---
+
+## ExecuteReaderList
+
+Читает все строки и собирает их в `List`.
+
+```csharp
+// Простая проекция
+var names = await dataSource.ExecuteReaderList(
+ "SELECT name FROM users ORDER BY name",
+ reader => reader.GetString(0));
+
+// С параметрами
+var activeUsers = await dataSource.ExecuteReaderList<(int Id, string Name)>(
+ """SELECT id, name FROM users WHERE active = @active ORDER BY name""",
+ reader => (reader.GetInt32(0), reader.GetString(1)),
+ [new NpgsqlParameter { ParameterName = "active", Value = true }]);
+```
+
+---
+
+## ExecuteReaderFirst
+
+Возвращает первое значение из первого столбца первой строки. Возвращает `default(T)` если результат пуст.
+
+```csharp
+string name = await dataSource.ExecuteReaderFirst("SELECT name FROM users WHERE id = 42");
+// → "Tom" или default(string) если не найдено
+```
+
+Поддерживаемые типы: `int`, `long`, `short`, `bool`, `double`, `decimal`, `char`, `string`, `DateTime`, `Guid`, `DateTimeOffset`.
+
+---
+
+## BeginBinaryImport
+
+Быстрый бинарный импорт через COPY BINARY.
+
+```csharp
+ulong imported = await dataSource.BeginBinaryImport(
+ "COPY users (name, email) FROM stdin BINARY",
+ async (writer, ct) =>
+ {
+ foreach (var user in users)
+ {
+ await writer.StartRowAsync(ct);
+ await writer.WriteAsync(user.Name, ct);
+ await writer.WriteAsync(user.Email, ct);
+ }
+ return await writer.CompleteAsync(ct);
+ },
+ cancellationToken);
+
+Console.WriteLine($"Imported {imported} rows");
+```
+
+---
+
+## PgRetryStrategy
+
+Повторы с jitter для транзитных ошибок Npgsql.
+
+```csharp
+using Sa.Data.PostgreSql;
+
+// Автоматически повторяет при транзитных ошибках (сброс соединения, таймаут и т.д.)
+var result = await PgRetryStrategy.ExecuteWithRetry(
+ async ct =>
+ {
+ using var conn = await dataSource.OpenDbConnection(ct);
+ return await conn.OpenAsync(ct);
+ },
+ retryCount: 5,
+ initialDelay: 530);
+```
+
+---
+
+## DbCommandExtensions + INamePrefixProvider
+
+Оптимизированный API для добавления параметризированных команд с предварительно закэшированными именами параметров (минимальные аллокации).
+
+```csharp
+// Объявите провайдер префиксов
+public class UserParams : INamePrefixProvider
+{
+ public static string[] GetPrefixes() => ["name", "age", "email"];
+ public static int MaxIndex => 10;
+}
+
+// Используйте — имена генерируются как @name0, @name1, ..., @age0, ...
+var cmd = new NpgsqlCommand("SELECT * FROM users WHERE name = @name0 AND age > @age0")
+ .AddParam("name", "Tom", 0)
+ .AddParam("age", 18, 0);
+```
+
+---
+
+## Сравнение методов
+
+| Метод | Возврат | Когда использовать |
+|-------|---------|-------------------|
+| `ExecuteNonQuery` | `int` (строки) | INSERT / UPDATE / DELETE / DDL |
+| `ExecuteScalar` | `object?` | Одиночное значение, нужна ручная casts |
+| `ExecuteScalarTyped` | `T` | Одиночное значение с авто-кастомом (Guid, DateTime, DateTimeOffset, DateOnly) |
+| `ExecuteReader` | `int` (строки) | Потоковая обработка, много строк |
+| `ExecuteReaderList` | `List` | Маленький результат, собрать всё |
+| `ExecuteReaderFirst` | `T` | Одна строка, одна колонка |
+| `BeginBinaryImport` | `ulong` (строки) | Массовый импорт через COPY BINARY |
+| `ExecuteTransactionAsync` | `void` | Атомарные операции с rollback |
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.Data.PostgreSql/Readme.md b/src/Sa.Data.PostgreSql/Readme.md
index 63e70695..6882926d 100644
--- a/src/Sa.Data.PostgreSql/Readme.md
+++ b/src/Sa.Data.PostgreSql/Readme.md
@@ -1,87 +1,227 @@
-# IPgDataSource
+# Sa.Data.PostgreSql
-Provides a lightweight (minimal) abstraction for working with PostgreSQL databases in .NET applications.
+Lightweight Npgsql wrapper for common PostgreSQL operations — no ORM overhead, with DI, Native AOT support, and minimal allocations.
+
+---
+
+## Quick Start
+
+```csharp
+// Option 1: direct creation
+var dataSource = IPgDataSource.Create("Host=db;Database=mydb;Username=usr;Password=pwd");
+
+// Option 2: via DI
+services.AddSaPostgreSqlDataSource(b => b.WithConnectionString("Host=db;Database=mydb;Username=usr;Password=pwd"));
+// or with factory (e.g., from IConfiguration):
+services.AddSaPostgreSqlDataSource(b => b.WithConnectionString(sp =>
+ sp.GetRequiredService().GetConnectionString("Default")));
+```
+
+---
## ExecuteNonQuery
-Executes an SQL query that does not return data (e.g., INSERT, UPDATE, DELETE) and returns the number of affected rows.
+Executes a SQL command that doesn't return data (INSERT / UPDATE / DELETE / DDL) and returns the number of affected rows.
```csharp
-var dataSource = new PgDataSource(new PgDataSourceSettings("YourConnectionString"));
-int affectedRows = await dataSource.ExecuteNonQuery("SELECT 2");
-Console.WriteLine($"Affected Rows: {affectedRows}");
+// Simple query
+int affected = await dataSource.ExecuteNonQuery("DELETE FROM sessions WHERE expired = true");
+
+// With parameters
+int affected = await dataSource.ExecuteNonQuery("""
+ INSERT INTO users (name, age) VALUES (@p0, @p1);
+ """, [
+ new NpgsqlParameter { ParameterName = "p0", Value = "Tom" },
+ new NpgsqlParameter { ParameterName = "p1", Value = 18 }
+ ]);
+```
+
+---
+
+## ExecuteScalar / ExecuteScalarTyped
+
+Returns the first value of the first row in the result. `ExecuteScalarTyped` automatically casts the result, including support for `Guid`, `DateTime`, `DateTimeOffset`, and `DateOnly → DateTime`.
+
+```csharp
+// object? overload
+object? count = await dataSource.ExecuteScalar("SELECT COUNT(*) FROM users");
+
+// Typed overload
+int count = await dataSource.ExecuteScalarTyped("SELECT COUNT(*) FROM users");
+long id = await dataSource.ExecuteScalarTyped("SELECT nextval('users_id_seq')");
+Guid tenantId = await dataSource.ExecuteScalarTyped("SELECT tenant_uuid FROM tenants LIMIT 1");
+```
+
+---
-var parameters = new[]
+## ExecuteReader
+
+Streaming row reading with a callback — ideal for processing large results without loading into memory.
+
+```csharp
+int processed = 0;
+await dataSource.ExecuteReader("SELECT id, name FROM users", (reader, rowIndex) =>
{
- new NpgsqlParameter("p1", "Tom"),
- new NpgsqlParameter("p2", 18)
-};
+ int id = reader.GetInt32(0);
+ string name = reader.GetString(1);
+ Console.WriteLine($"{rowIndex}: {id} → {name}");
+ processed++;
+});
+Console.WriteLine($"Processed {processed} rows");
+```
-int affectedRows = await dataSource.ExecuteNonQuery("""
- CREATE TABLE IF NOT EXISTS users (
- name text,
- age int
- );
+---
- INSERT INTO users (name, age) VALUES (@p1, @p2);
- """, parameters);
+## ExecuteReaderList
-Console.WriteLine($"Affected Rows: {affectedRows}");
+Reads all rows and collects them into `List`.
+
+```csharp
+// Simple projection
+var names = await dataSource.ExecuteReaderList(
+ "SELECT name FROM users ORDER BY name",
+ reader => reader.GetString(0));
+
+// With parameters
+var activeUsers = await dataSource.ExecuteReaderList<(int Id, string Name)>(
+ """SELECT id, name FROM users WHERE active = @active ORDER BY name""",
+ reader => (reader.GetInt32(0), reader.GetString(1)),
+ [new NpgsqlParameter { ParameterName = "active", Value = true }]);
```
-## ExecuteReader
+---
+
+## ExecuteReaderFirst
+
+Returns the first value from the first column of the first row. Returns `default(T)` if the result is empty.
+
+Supported types: `int`, `long`, `short`, `bool`, `double`, `decimal`, `char`, `string`, `DateTime`, `Guid`, `DateTimeOffset`.
+
+```csharp
+// Returns 0 if the table is empty
+int errorCount = await dataSource.ExecuteReaderFirst(
+ "SELECT COUNT(*) FROM outbox_errors");
+
+// Guid — automatic casting works
+Guid firstTenantId = await dataSource.ExecuteReaderFirst(
+ "SELECT tenant_id FROM tenants LIMIT 1");
+```
+
+---
+
+## ExecuteTransactionAsync
-Reading Data
+Atomic transaction with automatic rollback on error.
```csharp
-int actual = 0;
-await dataSource.ExecuteReader("SELECT 1", (reader, i) => actual = reader.GetInt32(0));
-Console.WriteLine($"Value from Database: {actual}");
+await dataSource.ExecuteTransactionAsync(async (transaction, ct) =>
+{
+ // All commands inside use one transaction
+ await dataSource.ExecuteNonQuery(
+ "INSERT INTO accounts (balance) VALUES (0)", ct);
+
+ await dataSource.ExecuteNonQuery(
+ "INSERT INTO transactions (account_id, amount) VALUES (1, 100)", ct);
-// get first value
-int errCount = await fixture.DataSource.ExecuteReaderFirst("select count(error_id) from outbox__$error");
+ // On success — auto-commit
+}, IsolationLevel.ReadCommitted, ct);
+// On any exception — auto-rollback
+try
+{
+ await dataSource.ExecuteTransactionAsync(async (tx, ct) =>
+ {
+ throw new InvalidOperationException("Oops");
+ }, ct);
+}
+catch (InvalidOperationException)
+{
+ // Transaction rolled back automatically
+}
```
+---
+
## BeginBinaryImport
-Binary Import
+Fast binary data import via COPY — orders of magnitude faster than individual INSERTs.
```csharp
-public async ValueTask BulkWrite(ReadOnlyMemory> messages CancellationToken cancellationToken){
- // Start binary import
- ulong result = await dataSource.BeginBinaryImport(sqlTemplate, async (writer, t) =>
+ulong imported = await dataSource.BeginBinaryImport(
+ "COPY bulk_data (id, payload, created_at) FROM STDIN BINARY",
+ async (writer, ct) =>
{
- // Write rows to import
- WriteRows(writer, typeCode, messages);
- return await writer.CompleteAsync(t);
- }, cancellationToken);
+ foreach (var item in items)
+ {
+ writer.StartRow();
+ writer.Write(item.Id, NpgsqlDbType.Integer);
+ writer.Write(item.Payload, NpgsqlDbType.Bytea);
+ writer.Write(item.CreatedAt.ToUnixTimeMilliseconds(), NpgsqlDbType.Timestamp);
+ }
+ return await writer.CompleteAsync(ct);
+ },
+ cancellationToken);
+
+Console.WriteLine($"Imported {imported} rows");
+```
- return result;
-}
+---
-private void WriteRows(NpgsqlBinaryImporter writer, ReadOnlyMemory> messages)
-{
- foreach (OutboxMessage message in messages.Span)
+## PgRetryStrategy
+
+Retry with jitter for transient Npgsql errors.
+
+```csharp
+using Sa.Data.PostgreSql;
+
+// Automatically retries on transient errors (connection reset, timeout, etc.)
+var result = await PgRetryStrategy.ExecuteWithRetry(
+ async ct =>
{
- // Generate a unique identifier for the message
- string id = idGenerator.GenId(message.PartInfo.CreatedAt);
-
- // Start a new row for writing
- writer.StartRow();
-
- // Write data to the row
- writer.Write(id, NpgsqlDbType.Char); // id
- writer.Write(message.PartInfo.TenantId, NpgsqlDbType.Integer); // tenant
- writer.Write(message.PartInfo.Part, NpgsqlDbType.Text); // part
-
- // Serialize and write the payload
- using RecyclableMemoryStream stream = streamManager.GetStream();
- serializer.Serialize(stream, message.Payload);
- stream.Position = 0;
- writer.Write(stream, NpgsqlDbType.Bytea); // payload
- writer.Write(stream.Length, NpgsqlDbType.Integer); // payload_size
- writer.Write(message.PartInfo.CreatedAt.ToUnixTimeSeconds(), NpgsqlDbType.Bigint); // created_at
- }
+ using var conn = await dataSource.OpenDbConnection(ct);
+ return await conn.OpenAsync(ct);
+ },
+ retryCount: 5,
+ initialDelay: 530);
+```
+
+---
+
+## DbCommandExtensions + INamePrefixProvider
+
+Optimized API for adding parameterized commands with pre-cached parameter names (minimal allocations).
+
+```csharp
+// Declare a prefix provider
+public class UserParams : INamePrefixProvider
+{
+ public static string[] GetPrefixes() => ["name", "age", "email"];
+ public static int MaxIndex => 10;
}
-```
\ No newline at end of file
+
+// Use — names are generated as @name0, @name1, ..., @age0, ...
+var cmd = new NpgsqlCommand("SELECT * FROM users WHERE name = @name0 AND age > @age0")
+ .AddParam("name", "Tom", 0)
+ .AddParam("age", 18, 0);
+```
+
+---
+
+## Method Comparison
+
+| Method | Return | When to use |
+|--------|--------|-------------|
+| `ExecuteNonQuery` | `int` (rows) | INSERT / UPDATE / DELETE / DDL |
+| `ExecuteScalar` | `object?` | Single value, manual cast needed |
+| `ExecuteScalarTyped` | `T` | Single value with auto-cast (Guid, DateTime, DateTimeOffset, DateOnly) |
+| `ExecuteReader` | `int` (rows) | Streaming processing, many rows |
+| `ExecuteReaderList` | `List` | Small result, collect everything |
+| `ExecuteReaderFirst` | `T` | One row, one column |
+| `BeginBinaryImport` | `ulong` (rows) | Mass import via COPY BINARY |
+| `ExecuteTransactionAsync` | `void` | Atomic operations with rollback |
+
+---
+
+## License
+
+MIT
diff --git a/src/Sa.Data.PostgreSql/Sa.Data.PostgreSql.csproj b/src/Sa.Data.PostgreSql/Sa.Data.PostgreSql.csproj
index 1862684d..e3e4f2ba 100644
--- a/src/Sa.Data.PostgreSql/Sa.Data.PostgreSql.csproj
+++ b/src/Sa.Data.PostgreSql/Sa.Data.PostgreSql.csproj
@@ -3,7 +3,7 @@
- 0.9.0
+ 0.10.0
Simple client for Npqsql
diff --git a/src/Sa.Data.PostgreSql/Setup.cs b/src/Sa.Data.PostgreSql/Setup.cs
index 66e5ce5c..ec50b64a 100644
--- a/src/Sa.Data.PostgreSql/Setup.cs
+++ b/src/Sa.Data.PostgreSql/Setup.cs
@@ -28,7 +28,7 @@ public static IServiceCollection AddSaPostgreSqlDataSource(
return new PgDataSource(settings);
});
- services.TryAddSingleton();
+
return services;
}
}
diff --git a/src/Sa.Data.S3/README.md b/src/Sa.Data.S3/README.md
index d8d3c9c2..a88e5ca8 100644
--- a/src/Sa.Data.S3/README.md
+++ b/src/Sa.Data.S3/README.md
@@ -1,64 +1,135 @@
# Sa.Data.S3
-This is a fork of https://github.com/teoadal/Storage , which is a wrapper around HttpClient for working with S3-compatible storage. It offers performance comparable to MinIO while consuming almost 200 times less memory than the AWS SDK client.
+Wrapper over `HttpClient` for working with S3-compatible storage systems (Minio, AWS S3, DigitalOcean Spaces, etc.). Fully self-implemented AWS Signature Version 4 — **no dependencies on AWS SDK or Minio SDK**.
-## Forked
+---
-- https://github.com/dundich/Storage;
-- https://github.com/teoadal/Storage;
+## Motivation
+This is a fork of https://github.com/teoadal/Storage. Motivation: the [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/welcome.html) (4.x) and [Minio .NET](https://github.com/minio/minio-dotnet) (6.x) clients consumed too much memory. Result: speed is comparable to AWS, while memory consumption is ~150× lower than Minio SDK and ~17× lower than AWS SDK.
-Это обертка над HttpClient для работы с S3 хранилищами. Мотивация создания была простейшей - я не понимал,
-почему клиенты [AWS](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/welcome.html) (4.0.0)
-и [Minio](https://github.com/minio/minio-dotnet) (6.0.4) потребляют так много памяти. Результат экспериментов: скорость
-почти как у AWS, а потребление памяти почти в 150 раз меньше, чем клиент для Minio (и в 17 для AWS).
-
+---
## Creating a Client
-To interact with an S3-compatible storage system, you need to create a client using the provided configuration. Below is a detailed explanation of the code snippet and its parameters.
+### Without DI
```csharp
-
-var client = new S3BucketClient(new HttpClient(), new S3BucketClientSettings
+var client = new S3BucketClient(new HttpClient(), new S3BucketClientSetupSettings
{
- Bucket = "mybucket",
- Endpoint = "http://localhost:9000",
- AccessKey = "ROOTUSER",
- SecretKey = "ChangeMe123"
-};
-
+ Bucket = "mybucket",
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123"
+});
```
-## IS3BucketClient
+### With DI
```csharp
+services.AddSaS3BucketClient(new S3BucketClientSetupSettings
+{
+ Bucket = "mybucket",
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ TotalRequestTimeout = TimeSpan.FromSeconds(180),
+ ConnectionPoolLifetime = TimeSpan.FromMinutes(15),
+ HandlerLifetime = Timeout.InfiniteTimeSpan // or TimeSpan.FromHours(2) for periodic handler refresh
+});
+
+// Usage:
+var client = serviceProvider.GetRequiredService();
+```
+
+---
+
+## Settings
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `AccessKey` | S3 access key | *(required)* |
+| `SecretKey` | S3 secret key | *(required)* |
+| `Bucket` | Bucket name | *(required)* |
+| `Endpoint` | S3 storage URL | *(required)* |
+| `Region` | Region for SigV4 | `"us-east-1"` |
+| `Service` | Service name for SigV4 | `"s3"` |
+| `UseHttp2` | Force HTTP/2 | `false` |
+| `TotalRequestTimeout` | Per-request timeout | `180 sec` |
+| `ConnectionPoolLifetime` | Connection pool lifetime | `15 min` |
+| `HandlerLifetime` | HttpClient handler lifetime | `∞` (infinite) |
+---
+
+## API
+
+### IBucketOperations
+
+```csharp
public interface IBucketOperations
{
- Task CreateBucket(CancellationToken ct);
- Task DeleteBucket(CancellationToken ct);
- Task IsBucketExists(CancellationToken ct);
+ Task CreateBucket(CancellationToken ct);
+ Task DeleteBucket(CancellationToken ct);
+ Task DeleteBucket(bool forceDelete, CancellationToken ct); // force: delete all objects before removing bucket
+ Task IsBucketExists(CancellationToken ct);
}
+```
+
+### IFileOperations
+```csharp
public interface IFileOperations
{
- string BuildFileUrl(string fileName);
- string BuildFileUrl(string fileName, TimeSpan expiration);
- Task DeleteFile(string fileName, CancellationToken ct);
- Task GetFile(string fileName, CancellationToken ct);
- Task GetFileStream(string fileName, CancellationToken ct);
- Task GetFileUrl(string fileName, TimeSpan expiration, CancellationToken ct);
- Task IsFileExists(string fileName, CancellationToken ct);
- IAsyncEnumerable List(string? prefix, CancellationToken ct);
- Task UploadFile(string fileName, string contentType, byte[] data, CancellationToken ct);
- Task UploadFile(string fileName, string contentType, CancellationToken ct);
- Task UploadFile(string fileName, string contentType, Stream data, CancellationToken ct);
+ string BuildFileUrl(string fileName);
+ string BuildFileUrl(string fileName, TimeSpan expiration);
+ Task DeleteFile(string fileName, CancellationToken ct);
+ Task GetFile(string fileName, CancellationToken ct);
+ Task GetFileStream(string fileName, CancellationToken ct);
+ Task GetFileUrl(string fileName, TimeSpan expiration, CancellationToken ct);
+ Task IsFileExists(string fileName, CancellationToken ct);
+ IAsyncEnumerable List(string? prefix, CancellationToken ct); // with pagination
+ Task UploadFile(string fileName, string contentType, byte[] data, CancellationToken ct);
+ Task UploadFile(string fileName, string contentType, CancellationToken ct); // manual multipart
+ Task UploadFile(string fileName, string contentType, Stream data, CancellationToken ct);
}
+```
+
+### Manual Multipart Upload
-public interface IS3BucketClient: IBucketOperations, IFileOperations
+For files > 5MB, multipart upload is selected automatically. For manual control:
+
+```csharp
+using var uploader = await client.UploadFile("large-file.bin", "application/octet-stream", ct);
+
+uploader.AddPart(chunkData, ct);
+uploader.AddPart(chunkData, offset, length, ct); // overload with offset
+uploader.AddParts(fullDataStream, ct);
+uploader.AddParts(fullByteArray, ct);
+
+if (await uploader.Complete(ct))
+{
+ Console.WriteLine($"Uploaded {uploader.Written} bytes");
+}
+else
{
- string Bucket { get; }
- Uri Endpoint { get; }
+ await uploader.Abort(ct);
}
```
+
+---
+
+## Implementation Details
+
+- **AWS SigV4** — full manual implementation of request signing (SHA256 + HMAC-SHA256 chain)
+- **ArrayPool.Shared** — buffer pooling to minimize GC pressure
+- **ref struct ValueStringBuilder** — stack-based string builder with zero allocations
+- **stackalloc** — wherever possible to avoid heap allocation
+- **Buffered XML parser** — efficient reading of S3 responses (ListObjects, Multipart IDs)
+- **Pagination** — automatic handling of `IsTruncated` / `NextContinuationToken` in `List()`
+- **CancellationToken** — supported in all async operations
+
+---
+
+## License
+
+MIT
diff --git a/src/Sa.Data.S3/Readme-ru.md b/src/Sa.Data.S3/Readme-ru.md
new file mode 100644
index 00000000..2f949535
--- /dev/null
+++ b/src/Sa.Data.S3/Readme-ru.md
@@ -0,0 +1,135 @@
+# Sa.Data.S3
+
+Обёртка над `HttpClient` для работы с S3-совместимыми хранилищами (Minio, AWS S3, DigitalOcean Spaces и др.). Полностью собственная реализация AWS Signature Version 4 — **без зависимостей от AWS SDK или Minio SDK**.
+
+---
+
+## Мотивация
+
+Это форк https://github.com/teoadal/Storage. Мотивация: клиенты [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/welcome.html) (4.x) и [Minio .NET](https://github.com/minio/minio-dotnet) (6.x) потребляли слишком много памяти. Результат: скорость почти как у AWS, а потребление памяти в ~150 раз меньше Minio SDK и в ~17 раз меньше AWS SDK.
+
+---
+
+## Создание клиента
+
+### Без DI
+
+```csharp
+var client = new S3BucketClient(new HttpClient(), new S3BucketClientSetupSettings
+{
+ Bucket = "mybucket",
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123"
+});
+```
+
+### С DI
+
+```csharp
+services.AddSaS3BucketClient(new S3BucketClientSetupSettings
+{
+ Bucket = "mybucket",
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ TotalRequestTimeout = TimeSpan.FromSeconds(180),
+ ConnectionPoolLifetime = TimeSpan.FromMinutes(15),
+ HandlerLifetime = Timeout.InfiniteTimeSpan // или TimeSpan.FromHours(2) для периодического обновления handler
+});
+
+// Использование:
+var client = serviceProvider.GetRequiredService();
+```
+
+---
+
+## Настройки
+
+| Свойство | Описание | По умолчанию |
+|----------|----------|-------------|
+| `AccessKey` | Ключ доступа S3 | *(обязательно)* |
+| `SecretKey` | Секретный ключ S3 | *(обязательно)* |
+| `Bucket` | Имя бакета | *(обязательно)* |
+| `Endpoint` | URL S3-хранилища | *(обязательно)* |
+| `Region` | Регион для SigV4 | `"us-east-1"` |
+| `Service` | Сервис для SigV4 | `"s3"` |
+| `UseHttp2` | Принудительный HTTP/2 | `false` |
+| `TotalRequestTimeout` | Таймаут каждого запроса | `180 сек` |
+| `ConnectionPoolLifetime` | Время жизни пула соединений | `15 мин` |
+| `HandlerLifetime` | Время жизни HttpClient handler | `∞` (бесконечность) |
+
+---
+
+## API
+
+### IBucketOperations
+
+```csharp
+public interface IBucketOperations
+{
+ Task CreateBucket(CancellationToken ct);
+ Task DeleteBucket(CancellationToken ct);
+ Task DeleteBucket(bool forceDelete, CancellationToken ct); // force: удалить все объекты перед удалением bucket
+ Task IsBucketExists(CancellationToken ct);
+}
+```
+
+### IFileOperations
+
+```csharp
+public interface IFileOperations
+{
+ string BuildFileUrl(string fileName);
+ string BuildFileUrl(string fileName, TimeSpan expiration);
+ Task DeleteFile(string fileName, CancellationToken ct);
+ Task GetFile(string fileName, CancellationToken ct);
+ Task GetFileStream(string fileName, CancellationToken ct);
+ Task GetFileUrl(string fileName, TimeSpan expiration, CancellationToken ct);
+ Task IsFileExists(string fileName, CancellationToken ct);
+ IAsyncEnumerable List(string? prefix, CancellationToken ct); // с pagination
+ Task UploadFile(string fileName, string contentType, byte[] data, CancellationToken ct);
+ Task UploadFile(string fileName, string contentType, CancellationToken ct); // ручной multipart
+ Task UploadFile(string fileName, string contentType, Stream data, CancellationToken ct);
+}
+```
+
+### Ручной Multipart Upload
+
+Для файлов > 5MB автоматически выбирается multipart upload. Для ручного управления:
+
+```csharp
+using var uploader = await client.UploadFile("large-file.bin", "application/octet-stream", ct);
+
+uploader.AddPart(chunkData, ct);
+uploader.AddPart(chunkData, offset, length, ct); // перегрузка с offset
+uploader.AddParts(fullDataStream, ct);
+uploader.AddParts(fullByteArray, ct);
+
+if (await uploader.Complete(ct))
+{
+ Console.WriteLine($"Uploaded {uploader.Written} bytes");
+}
+else
+{
+ await uploader.Abort(ct);
+}
+```
+
+---
+
+## Особенности реализации
+
+- **AWS SigV4** — полная ручная реализация подписывания запросов (SHA256 + HMAC-SHA256 chain)
+- **ArrayPool.Shared** — пулинг буферов для минимизации GC pressure
+- **ref struct ValueStringBuilder** — стек-based строковый билдер без аллокаций
+- **stackalloc** — везде где возможно для избежания heap allocation
+- **Буферизированный XML парсер** — эффективное чтение ответов S3 (ListObjects, Multipart IDs)
+- **Pagination** — автоматическая обработка `IsTruncated` / `NextContinuationToken` в `List()`
+- **CancellationToken** — поддерживается во всех async операциях
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.Data.S3/S3BucketClient.Buckets.cs b/src/Sa.Data.S3/S3BucketClient.Buckets.cs
index af86336d..426de0ba 100644
--- a/src/Sa.Data.S3/S3BucketClient.Buckets.cs
+++ b/src/Sa.Data.S3/S3BucketClient.Buckets.cs
@@ -6,7 +6,7 @@ namespace Sa.Data.S3;
///
/// Функции управления бакетом
///
-public partial class S3BucketClient : IBucketOperations
+public sealed partial class S3BucketClient : IBucketOperations
{
public async Task CreateBucket(CancellationToken ct)
{
@@ -32,6 +32,21 @@ public async Task CreateBucket(CancellationToken ct)
public async Task DeleteBucket(CancellationToken ct)
{
+ return await DeleteBucket(forceDelete: false, ct).ConfigureAwait(false);
+ }
+
+ ///
+ /// Удаляет бакет. Если forceDelete=true — сначала удаляет все объекты из бакета.
+ ///
+ /// Если true, предварительно удалит все объекты в бакете
+ /// Токен отмены операции
+ public async Task DeleteBucket(bool forceDelete, CancellationToken ct)
+ {
+ if (forceDelete)
+ {
+ await DeleteAllObjects(ct).ConfigureAwait(false);
+ }
+
HttpResponseMessage response;
using (var request = CreateRequest(HttpMethod.Delete))
{
@@ -52,6 +67,29 @@ public async Task DeleteBucket(CancellationToken ct)
}
}
+ private async Task DeleteAllObjects(CancellationToken ct)
+ {
+ var prefixes = new List();
+ await foreach (var key in List(null, ct).ConfigureAwait(false))
+ {
+ prefixes.Add(key);
+ }
+
+ // S3 SelectObjectCancel требует удаления по ключам, не по prefix
+ // Перечитаем всё по ключам и удалим
+ foreach (var key in prefixes)
+ {
+ try
+ {
+ await DeleteFile(key, ct).ConfigureAwait(false);
+ }
+ catch
+ {
+ // Ignore individual delete failures during force cleanup
+ }
+ }
+ }
+
public async Task IsBucketExists(CancellationToken ct)
{
HttpResponseMessage response;
diff --git a/src/Sa.Data.S3/S3BucketClientSetupSettings.cs b/src/Sa.Data.S3/S3BucketClientSetupSettings.cs
index 5c58ace9..2030f7d2 100644
--- a/src/Sa.Data.S3/S3BucketClientSetupSettings.cs
+++ b/src/Sa.Data.S3/S3BucketClientSetupSettings.cs
@@ -2,5 +2,19 @@
public sealed class S3BucketClientSetupSettings : S3BucketSettings
{
+ ///
+ /// Максимальное время ожидания ответа сервера для каждого запроса. По умолчанию: 180 секунд.
+ ///
public TimeSpan TotalRequestTimeout { get; set; } = TimeSpan.FromSeconds(180);
+
+ ///
+ /// Время жизни пула соединений в SocketsHttpHandler. По умолчанию: 15 минут.
+ ///
+ public TimeSpan ConnectionPoolLifetime { get; set; } = TimeSpan.FromMinutes(15);
+
+ ///
+ /// Время жизни обработчика HttpClient. По умолчанию: бесконечность (для long-running сервисов).
+ /// Установите в TimeSpan.FromHours(2) для периодического пересоздания handler и освобождения stale connections.
+ ///
+ public TimeSpan HandlerLifetime { get; set; } = Timeout.InfiniteTimeSpan;
}
diff --git a/src/Sa.Data.S3/S3Stream.cs b/src/Sa.Data.S3/S3Stream.cs
index 07795b26..8a379802 100644
--- a/src/Sa.Data.S3/S3Stream.cs
+++ b/src/Sa.Data.S3/S3Stream.cs
@@ -74,9 +74,12 @@ public override void Write(byte[] buffer, int offset, int count)
protected override void Dispose(bool disposing)
{
- stream.Dispose();
- response.Dispose();
+ if (disposing)
+ {
+ stream.Dispose();
+ response.Dispose();
+ }
- base.Dispose(true);
+ base.Dispose(disposing);
}
}
diff --git a/src/Sa.Data.S3/S3Upload.cs b/src/Sa.Data.S3/S3Upload.cs
index 7f1e226c..fb5577ba 100644
--- a/src/Sa.Data.S3/S3Upload.cs
+++ b/src/Sa.Data.S3/S3Upload.cs
@@ -103,7 +103,7 @@ public async Task AddPart(byte[] data, int length, CancellationToken ct)
}
var partId = await _client.MultipartPutPart(
- _encodedFileName, UploadId, _partCount + 1, data, length, ct);
+ _encodedFileName, UploadId, _partCount + 1, data, length, ct).ConfigureAwait(false);
if (string.IsNullOrEmpty(partId))
{
diff --git a/src/Sa.Data.S3/Sa.Data.S3.csproj b/src/Sa.Data.S3/Sa.Data.S3.csproj
index 8bb96edb..c52b3843 100644
--- a/src/Sa.Data.S3/Sa.Data.S3.csproj
+++ b/src/Sa.Data.S3/Sa.Data.S3.csproj
@@ -3,7 +3,7 @@
- 0.9.0
+ 0.10.0
Sa.Data.S3
Simple client for S3 (Sa.Data.S3)
s3
diff --git a/src/Sa.Data.S3/Setup.cs b/src/Sa.Data.S3/Setup.cs
index 224c1834..ac065e98 100644
--- a/src/Sa.Data.S3/Setup.cs
+++ b/src/Sa.Data.S3/Setup.cs
@@ -19,9 +19,9 @@ public static IServiceCollection AddSaS3BucketClient(
})
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler()
{
- PooledConnectionLifetime = TimeSpan.FromMinutes(15)
+ PooledConnectionLifetime = settings.ConnectionPoolLifetime
})
- .SetHandlerLifetime(Timeout.InfiniteTimeSpan)
+ .SetHandlerLifetime(settings.HandlerLifetime)
.AddStandardResilienceHandler(options =>
{
options.TotalRequestTimeout.Timeout = settings.TotalRequestTimeout;
diff --git a/src/Sa.Data.S3/Utils/XmlStreamReader.cs b/src/Sa.Data.S3/Utils/XmlStreamReader.cs
index 13b3792a..fd392dcb 100644
--- a/src/Sa.Data.S3/Utils/XmlStreamReader.cs
+++ b/src/Sa.Data.S3/Utils/XmlStreamReader.cs
@@ -12,7 +12,9 @@ public static string ReadString(Stream stream, ReadOnlySpan elementName, i
: buffer[..written].ToString();
}
+#pragma warning disable S3776
private static int ReadTo(Stream stream, ReadOnlySpan elementName, ref Span valueBuffer)
+#pragma warning restore S3776
{
var expectedIndex = 0;
var propertyLength = elementName.Length;
diff --git a/src/Sa.HybridFileStorage.FileSystem/FileSystemStorage.cs b/src/Sa.HybridFileStorage.FileSystem/FileSystemStorage.cs
index eba11144..6623b17e 100644
--- a/src/Sa.HybridFileStorage.FileSystem/FileSystemStorage.cs
+++ b/src/Sa.HybridFileStorage.FileSystem/FileSystemStorage.cs
@@ -1,5 +1,4 @@
using Sa.HybridFileStorage.Domain;
-using System.Globalization;
using System.Runtime.CompilerServices;
@@ -53,11 +52,11 @@ public async Task UploadAsync(
Stream fileStream,
CancellationToken cancellationToken)
{
- ArgumentNullException.ThrowIfNull(metadata);
- ArgumentException.ThrowIfNullOrWhiteSpace(metadata.FileName);
ArgumentNullException.ThrowIfNull(fileStream);
EnsureWritable();
+ metadata.Validate();
+
string filename = PathSanitizer.SanitizeRelativePath(metadata.FileName);
string relativePath = string.Concat(Basket, "/", metadata.TenantId.ToString(), "/", filename);
@@ -69,6 +68,13 @@ public async Task UploadAsync(
if (!string.IsNullOrEmpty(directory))
EnsureDirectory(directory);
+ // Smart preallocation: use actual length when available, fall back to 0 for unknown sizes
+ long preallocationSize = 1024 * 1024;
+ if (fileStream.CanSeek && fileStream.Length > 0 && fileStream.Length <= int.MaxValue)
+ {
+ preallocationSize = fileStream.Length;
+ }
+
await using var fileStreamOutput = new FileStream(filePath, new FileStreamOptions
{
Mode = FileMode.Create,
@@ -76,7 +82,7 @@ public async Task UploadAsync(
Share = FileShare.None,
BufferSize = _bufferSize,
Options = FileOptions.Asynchronous | FileOptions.SequentialScan,
- PreallocationSize = 5 * 1024 * 1024
+ PreallocationSize = (int)preallocationSize
});
await fileStream.CopyToAsync(fileStreamOutput, cancellationToken).ConfigureAwait(false);
@@ -96,6 +102,10 @@ public async Task DownloadAsync(
ArgumentNullException.ThrowIfNull(fileId);
ArgumentNullException.ThrowIfNull(loadStream);
+
+ if (!CanProcess(fileId))
+ return false;
+
string filePath = GetFullPath(fileId);
EnsurePathWithinBase(filePath);
@@ -110,8 +120,6 @@ public async Task DownloadAsync(
Options = FileOptions.Asynchronous | FileOptions.SequentialScan,
});
- if (fs == null || fs == Stream.Null) return false;
-
await loadStream(fs, cancellationToken).ConfigureAwait(false);
return true;
}
@@ -147,6 +155,9 @@ public async Task DeleteAsync(string fileId, CancellationToken cancellatio
ArgumentNullException.ThrowIfNull(fileId);
EnsureWritable();
+ if (!CanProcess(fileId))
+ return false;
+
var filePath = GetFullPath(fileId);
EnsurePathWithinBase(filePath);
@@ -213,35 +224,14 @@ private void EnsurePathWithinBase(string path)
if (!CanProcess(fileId))
return Task.FromResult(null);
- //parse: "storageType://basket/tenant/filename"
- ReadOnlySpan span = fileId.AsSpan();
- int schemeEnd = span.IndexOf(SchemeSeparator.AsSpan());
- if (schemeEnd == -1)
- return Task.FromResult(null);
-
- var pathPart = span[(schemeEnd + SchemeSeparator.Length)..];
-
- // "tenantId/filename"
- int slashIndex = pathPart.IndexOf('/');
- if (slashIndex == -1)
- return Task.FromResult(null);
-
- var scopeSpan = pathPart[..slashIndex];
-
- var nextSpan = pathPart[(slashIndex + 1)..];
- slashIndex = nextSpan.IndexOf('/');
-
- var tenantSpan = nextSpan[..slashIndex];
- var fileNameSpan = nextSpan[(slashIndex + 1)..];
-
- if (!int.TryParse(tenantSpan, NumberStyles.None, CultureInfo.InvariantCulture, out int tenantId))
+ if (!FileIdParser.TryParse(fileId, out var basket, out var tenantId, out _, out var fileName))
return Task.FromResult(null);
var metadata = new FileMetadata
{
StorageType = StorageType,
- Basket = scopeSpan.ToString(),
- FileName = fileNameSpan.ToString(),
+ Basket = basket,
+ FileName = fileName,
TenantId = tenantId
};
diff --git a/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageOptions.cs b/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageOptions.cs
index 649c756b..94100692 100644
--- a/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageOptions.cs
+++ b/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageOptions.cs
@@ -2,19 +2,42 @@
namespace Sa.HybridFileStorage.FileSystem;
+///
+/// Mutable configuration options for the filesystem file storage provider, used with fluent builder pattern.
+///
public sealed record FileSystemStorageOptions
{
+ ///
+ /// Gets or sets the storage type identifier. Defaults to ("fs").
+ ///
[Required]
[StringLength(10)]
public string StorageType { get; set; } = FileSystemStorageSettings.DefaultStorageType;
+
+ ///
+ /// Gets or sets the base directory path where files will be stored.
+ ///
[Required]
[StringLength(255)]
public string BasePath { get; set; } = string.Empty;
+
+ ///
+ /// Gets or sets a value indicating whether this storage is read-only. Defaults to false.
+ ///
public bool IsReadOnly { get; set; } = false;
+
+ ///
+ /// Gets or sets the basket (container) name. Must be 3–63 characters, start with a letter or underscore.
+ /// Defaults to ("share").
+ ///
[Required]
[StringLength(63, MinimumLength = 3)]
public string Basket { get; set; } = FileSystemStorageSettings.DefaultBasket;
+ ///
+ /// Validates the current configuration and throws a if any property is invalid.
+ ///
+ /// Thrown when , , or is invalid.
public void Validate()
{
if (string.IsNullOrWhiteSpace(BasePath))
diff --git a/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageSettings.cs b/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageSettings.cs
index 3d9b3c30..4f0136c3 100644
--- a/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageSettings.cs
+++ b/src/Sa.HybridFileStorage.FileSystem/FileSystemStorageSettings.cs
@@ -1,18 +1,42 @@
namespace Sa.HybridFileStorage.FileSystem;
+///
+/// Immutable settings for the filesystem file storage provider.
+///
public sealed record FileSystemStorageSettings
{
+ ///
+ /// Gets the storage type identifier. Defaults to ("fs").
+ ///
public string StorageType { get; init; } = DefaultStorageType;
+ ///
+ /// Gets the basket (container) name. Defaults to ("share").
+ ///
public string Basket { get; init; } = DefaultBasket;
+ ///
+ /// Gets the base directory path where files will be stored.
+ ///
public required string BasePath { get; init; }
+ ///
+ /// Gets a value indicating whether this storage is read-only. Defaults to false.
+ ///
public bool IsReadOnly { get; init; } = false;
+ ///
+ /// Gets the buffer size used for file I/O operations. Defaults to 256 KB.
+ ///
public int BufferSize { get; init; } = 256 * 1024;
-
+ ///
+ /// Gets the default storage type identifier.
+ ///
public const string DefaultStorageType = "fs";
+
+ ///
+ /// Gets the default basket name.
+ ///
public const string DefaultBasket = "share";
}
diff --git a/src/Sa.HybridFileStorage.FileSystem/README.md b/src/Sa.HybridFileStorage.FileSystem/README.md
new file mode 100644
index 00000000..9742e3e5
--- /dev/null
+++ b/src/Sa.HybridFileStorage.FileSystem/README.md
@@ -0,0 +1,242 @@
+# Sa.HybridFileStorage.FileSystem
+
+Local filesystem provider for `Sa.HybridFileStorage`. Stores files as physical files on disk with path sanitisation, security checks, and retry logic for transient I/O errors.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [File ID Format](#file-id-format)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+ - [Without DI](#without-di)
+ - [With DI](#with-di)
+- [CRUD Examples](#crud-examples)
+- [Settings Reference](#settings-reference)
+- [Security](#security)
+- [Error Handling](#error-handling)
+
+---
+
+## Overview
+
+`FileSystemStorage` implements `IFileStorage` backed by the local file system. Files are stored under a configurable base directory using the structure:
+
+```
+{BasePath}/{Basket}/{TenantId}/{FileName}
+```
+
+Key characteristics:
+- **Path sanitisation** — prevents directory traversal attacks
+- **Smart preallocation** — uses `FileStreamOptions.PreallocationSize` when stream length is known
+- **Retry helper** — retries `IOException` on delete operations
+- **Streaming reads/writes** — configurable buffer size for memory efficiency
+
+---
+
+## File ID Format
+
+```
+fs://{basket}/{tenantId}/{fileName}
+```
+
+**Examples:**
+- `fs://documents/42/report.pdf`
+- `fs://uploads/7/avatar.png`
+- `fs://share/100/data.bin`
+
+> Note: slashes and backslashes in `FileName` are sanitized to forward slashes and stripped of leading separators.
+
+---
+
+## Installation
+
+```powershell
+dotnet add package Sa.HybridFileStorage.FileSystem
+```
+
+---
+
+## Quick Start
+
+### Without DI
+
+```csharp
+using Sa.HybridFileStorage.FileSystem;
+using Sa.HybridFileStorage.Domain;
+
+var settings = new FileSystemStorageSettings
+{
+ BasePath = @"C:\data\files",
+ Basket = "documents"
+};
+
+using var storage = new FileSystemStorage(settings);
+
+// Upload
+using var stream = File.OpenRead(@"C:\temp\document.pdf");
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "document.pdf", TenantId = 42 },
+ stream, ct);
+
+Console.WriteLine(result.FileId); // fs://documents/42/document.pdf
+
+// Download
+bool found = await storage.DownloadAsync(result.FileId, async (fs, token) =>
+{
+ using var reader = new StreamReader(fs, Encoding.UTF8);
+ var content = await reader.ReadToEndAsync(token);
+ Console.WriteLine(content);
+}, ct);
+
+// Delete
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+```
+
+### With DI
+
+```csharp
+using Sa.HybridFileStorage.FileSystem;
+
+// Option 1: Immutable settings (recommended)
+builder.Services.AddSaFileSystemFileStorage(new FileSystemStorageSettings
+{
+ BasePath = @"C:\data\files",
+ Basket = "documents"
+});
+
+// Option 2: Mutable options with fluent builder
+builder.Services.AddSaFileSystemFileStorage((sp, options) =>
+{
+ options.BasePath = @"C:\data\files";
+ options.Basket = "documents";
+ options.IsReadOnly = false;
+ options.StorageType = "fs";
+});
+```
+
+---
+
+## CRUD Examples
+
+### Upload from Stream
+
+```csharp
+using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, world!"));
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "hello.txt", TenantId = 1 },
+ stream, ct);
+
+// File created at: {BasePath}/documents/1/hello.txt
+// File ID: fs://documents/1/hello.txt
+```
+
+### Upload from File
+
+Use `CopyFromFileAsync` from `Sa.HybridFileStorage` core:
+
+```csharp
+var result = await hybridStorage.CopyFromFileAsync(
+ filePath: @"C:\temp\large-video.mp4",
+ basket: "media",
+ input: new UploadFileInput { FileName = "video.mp4", TenantId = 5 },
+ bufferSize: 1024 * 1024, // 1 MB buffer for large files
+ ct: ct);
+```
+
+### Download to Memory
+
+```csharp
+byte[]? downloaded = default;
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ downloaded = await stream.ReadAllBytesAsync(token);
+}, ct);
+```
+
+### Download to Disk
+
+```csharp
+using var destination = new FileStream(@"C:\output\downloaded.pdf", FileMode.Create);
+await storage.DownloadAsync(result.FileId, async (source, token) =>
+ await source.CopyToAsync(destination, 81920, token),
+ ct);
+```
+
+### Get Metadata
+
+```csharp
+var metadata = await storage.GetMetadataAsync(result.FileId, ct);
+if (metadata != null)
+{
+ Console.WriteLine($"Basket: {metadata.Basket}");
+ Console.WriteLine($"Tenant: {metadata.TenantId}");
+ Console.WriteLine($"Name: {metadata.FileName}");
+ Console.WriteLine($"Type: {metadata.StorageType}");
+}
+```
+
+---
+
+## Settings Reference
+
+### FileSystemStorageSettings (immutable)
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `BasePath` | Root directory for all files | *(required)* |
+| `Basket` | Container name appended to BasePath | `"share"` |
+| `StorageType` | Scheme prefix in File ID | `"fs"` |
+| `IsReadOnly` | Prevent write/delete operations | `false` |
+| `BufferSize` | Read/write buffer size in bytes | `262144` (256 KB) |
+
+### FileSystemStorageOptions (mutable, fluent builder)
+
+Used with the `Action` overload:
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `BasePath` | Root directory for all files | *(required)* |
+| `Basket` | Container name | `"share"` |
+| `StorageType` | Scheme prefix in File ID | `"fs"` |
+| `IsReadOnly` | Prevent write/delete operations | `false` |
+
+Call `options.Validate()` after configuration to enforce required fields.
+
+---
+
+## Security
+
+`FileSystemStorage` protects against directory traversal attacks:
+
+1. **Path sanitisation** — leading `/` or `\` characters in `FileName` are stripped; all backslashes are converted to forward slashes
+2. **Base path containment** — every resolved file path is checked for belonging to `{BasePath}/{Basket}`. Attempts to escape via `../` are rejected with `SecurityException`
+3. **Deterministic paths** — File IDs map to relative paths without resolution, preventing symlink-based attacks
+
+```csharp
+// Safe — normalised to "report.pdf"
+new UploadFileInput { FileName = "/api/files/download/file/var/www/report.pdf" }
+// Creates: {BasePath}/documents/1/report.pdf
+
+// Blocked — directory traversal detected
+// fileName = "../../../etc/passwd" → throws SecurityException
+```
+
+---
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| `IsReadOnly = true` + upload/delete | Throws `HybridFileStorageWritableException` |
+| File not found during download/delete | Returns `false` (no exception) |
+| IOException on delete | Retries internally; returns `false` if all retries fail |
+| Path escape attempt | Throws `SecurityException` |
+| Invalid File ID format | Throws `ArgumentException` |
+
+---
+
+## License
+
+MIT
diff --git a/src/Sa.HybridFileStorage.FileSystem/Readme-ru.md b/src/Sa.HybridFileStorage.FileSystem/Readme-ru.md
new file mode 100644
index 00000000..6fd2ddc3
--- /dev/null
+++ b/src/Sa.HybridFileStorage.FileSystem/Readme-ru.md
@@ -0,0 +1,249 @@
+# Sa.HybridFileStorage.FileSystem
+
+Провайдер локальной файловой системы для `Sa.HybridFileStorage`. Хранит файлы как физические файлы на диске с санитизацией путей, проверками безопасности и логикой повтора при преходящих ошибках ввода-вывода.
+
+---
+
+## Содержание
+
+- [Обзор](#обзор)
+- [Формат File ID](#формат-file-id)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+ - [Без DI](#без-di)
+ - [С DI](#с-di)
+- [Примеры CRUD](#примеры-crud)
+- [Справочник настроек](#справочник-настроек)
+- [Безопасность](#безопасность)
+- [Обработка ошибок](#обработка-ошибок)
+
+---
+
+## Обзор
+
+`FileSystemStorage` реализует `IFileStorage` поверх локальной файловой системы. Файлы хранятся в настраиваемой корневой директории по структуре:
+
+```
+{BasePath}/{Basket}/{TenantId}/{FileName}
+```
+
+Ключевые особенности:
+- **Санитизация путей** — предотвращает атаки через обход директорий
+- **Умная преаллокация** — использует `FileStreamOptions.PreallocationSize`, когда длина потока известна
+- **Повтор (retry)** — повторяет `IOException` при операциях удаления
+- **Потоковое чтение/запись** — настраиваемый размер буфера для эффективности памяти
+
+---
+
+## Формат File ID
+
+```
+fs://{basket}/{tenantId}/{fileName}
+```
+
+**Примеры:**
+- `fs://documents/42/report.pdf`
+- `fs://uploads/7/avatar.png`
+- `fs://share/100/data.bin`
+
+> Примечание: слеши и обратные слеши в `FileName` санитизируются в прямые слеши и очищаются от ведущих разделителей.
+
+---
+
+## Установка
+
+```powershell
+dotnet add package Sa.HybridFileStorage.FileSystem
+```
+
+---
+
+## Быстрый старт
+
+### Без DI
+
+```csharp
+using Sa.HybridFileStorage.FileSystem;
+using Sa.HybridFileStorage.Domain;
+
+var settings = new FileSystemStorageSettings
+{
+ BasePath = @"C:\data\files",
+ Basket = "documents"
+};
+
+using var storage = new FileSystemStorage(settings);
+
+// Загрузка
+using var stream = File.OpenRead(@"C:\temp\document.pdf");
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "document.pdf", TenantId = 42 },
+ stream, ct);
+
+Console.WriteLine(result.FileId); // fs://documents/42/document.pdf
+
+// Скачивание
+bool found = await storage.DownloadAsync(result.FileId, async (fs, token) =>
+{
+ using var reader = new StreamReader(fs, Encoding.UTF8);
+ var content = await reader.ReadToEndAsync(token);
+ Console.WriteLine(content);
+}, ct);
+
+// Удаление
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+```
+
+### С DI
+
+```csharp
+using Sa.HybridFileStorage.FileSystem;
+
+// Вариант 1: неизменяемые настройки (рекомендуется)
+builder.Services.AddSaFileSystemFileStorage(new FileSystemStorageSettings
+{
+ BasePath = @"C:\data\files",
+ Basket = "documents"
+});
+
+// Вариант 2: изменяемые опции с fluent builder
+builder.Services.AddSaFileSystemFileStorage((sp, options) =>
+{
+ options.BasePath = @"C:\data\files";
+ options.Basket = "documents";
+ options.IsReadOnly = false;
+ options.StorageType = "fs";
+});
+```
+
+---
+
+## Примеры CRUD
+
+### Загрузка из Stream
+
+```csharp
+using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, world!"));
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "hello.txt", TenantId = 1 },
+ stream, ct);
+
+// Файл создан: {BasePath}/documents/1/hello.txt
+// File ID: fs://documents/1/hello.txt
+```
+
+### Загрузка из файла
+
+Используйте `CopyFromFileAsync` из ядра `Sa.HybridFileStorage`:
+
+```csharp
+var result = await hybridStorage.CopyFromFileAsync(
+ filePath: @"C:\temp\large-video.mp4",
+ basket: "media",
+ input: new UploadFileInput { FileName = "video.mp4", TenantId = 5 },
+ bufferSize: 1024 * 1024, // 1 MB буфер для больших файлов
+ ct: ct);
+```
+
+### Скачивание в память
+
+```csharp
+byte[]? downloaded = default;
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ downloaded = await stream.ReadAllBytesAsync(token);
+}, ct);
+```
+
+### Скачивание на диск
+
+```csharp
+using var destination = new FileStream(@"C:\output\downloaded.pdf", FileMode.Create);
+await storage.DownloadAsync(result.FileId, async (source, token) =>
+ await source.CopyToAsync(destination, 81920, token),
+ ct);
+```
+
+### Получение метаданных
+
+```csharp
+var metadata = await storage.GetMetadataAsync(result.FileId, ct);
+if (metadata != null)
+{
+ Console.WriteLine($"Корзина: {metadata.Basket}"); // documents
+ Console.WriteLine($"Тенант: {metadata.TenantId}"); // 42
+ Console.WriteLine($"Имя: {metadata.FileName}"); // report.pdf
+ Console.WriteLine($"Тип: {metadata.StorageType}"); // fs
+}
+```
+
+### Удаление
+
+```csharp
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+// Возвращает false, если файл не существует
+```
+
+---
+
+## Справочник настроек
+
+### FileSystemStorageSettings (неизменяемые)
+
+| Свойство | Описание | По умолчанию |
+|----------|----------|-------------|
+| `BasePath` | Корневая директория для всех файлов | *(обязательно)* |
+| `Basket` | Имя контейнера, добавляемое к BasePath | `"share"` |
+| `StorageType` | Префикс схемы в File ID | `"fs"` |
+| `IsReadOnly` | Запрет операций записи/удаления | `false` |
+| `BufferSize` | Размер буфера чтения/записи в байтах | `262144` (256 КБ) |
+
+### FileSystemStorageOptions (изменяемые, fluent builder)
+
+Используется с перегрузкой `Action`:
+
+| Свойство | Описание | По умолчанию |
+|----------|----------|-------------|
+| `BasePath` | Корневая директория для всех файлов | *(обязательно)* |
+| `Basket` | Имя контейнера | `"share"` |
+| `StorageType` | Префикс схемы в File ID | `"fs"` |
+| `IsReadOnly` | Запрет операций записи/удаления | `false` |
+
+Вызовите `options.Validate()` после конфигурации для проверки обязательных полей.
+
+---
+
+## Безопасность
+
+`FileSystemStorage` защищает от атак через обход директорий:
+
+1. **Санитизация путей** — ведущие символы `/` или `\` в `FileName` удаляются; все обратные слеши конвертируются в прямые
+2. **Контейнирование базового пути** — каждый разрешённый путь файла проверяется на принадлежность `{BasePath}/{Basket}`. Попытки побега через `../` отклоняются с `SecurityException`
+3. **Детерминированные пути** — File ID отображаются в относительные пути без вычисления, предотвращая атаки через симлинки
+
+```csharp
+// Безопасно — нормализуется до "report.pdf"
+new UploadFileInput { FileName = "/api/files/download/file/var/www/report.pdf" }
+// Создаёт: {BasePath}/documents/1/report.pdf
+
+// Заблокировано — обнаружен обход пути
+// fileName = "../../../etc/passwd" → выбрасывается SecurityException
+```
+
+---
+
+## Обработка ошибок
+
+| Сценарий | Поведение |
+|----------|----------|
+| `IsReadOnly = true` + загрузка/удаление | Выбрасывает `HybridFileStorageWritableException` |
+| Файл не найден при скачивании/удалении | Возвращает `false` (без исключения) |
+| IOException при удалении | Повторяется внутренне; возвращает `false`, если все повторы неудачны |
+| Попытка обхода пути | Выбрасывает `SecurityException` |
+| Неверный формат File ID | Выбрасывает `ArgumentException` |
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.HybridFileStorage.FileSystem/Sa.HybridFileStorage.FileSystem.csproj b/src/Sa.HybridFileStorage.FileSystem/Sa.HybridFileStorage.FileSystem.csproj
index a31b35b1..569c3ced 100644
--- a/src/Sa.HybridFileStorage.FileSystem/Sa.HybridFileStorage.FileSystem.csproj
+++ b/src/Sa.HybridFileStorage.FileSystem/Sa.HybridFileStorage.FileSystem.csproj
@@ -3,10 +3,15 @@
- 0.9.1
+ 0.10.0
File storage management
+
+
+
+
+
diff --git a/src/Sa.HybridFileStorage.FileSystem/Setup.cs b/src/Sa.HybridFileStorage.FileSystem/Setup.cs
index 2f903c96..02316681 100644
--- a/src/Sa.HybridFileStorage.FileSystem/Setup.cs
+++ b/src/Sa.HybridFileStorage.FileSystem/Setup.cs
@@ -3,9 +3,17 @@
namespace Sa.HybridFileStorage.FileSystem;
-
+///
+/// Provides extension methods for registering the filesystem file storage provider with the .NET Generic Host.
+///
public static class Setup
{
+ ///
+ /// Registers the filesystem file storage provider using immutable .
+ ///
+ /// The service collection to add the services to.
+ /// Immutable settings for the filesystem storage provider.
+ /// The same instance with the service added.
public static IServiceCollection AddSaFileSystemFileStorage(
this IServiceCollection services,
FileSystemStorageSettings options)
@@ -15,6 +23,12 @@ public static IServiceCollection AddSaFileSystemFileStorage(
return services;
}
+ ///
+ /// Registers the filesystem file storage provider using a mutable options builder with fluent configuration.
+ ///
+ /// The service collection to add the services to.
+ /// An action that receives an and a instance for fluent configuration.
+ /// The same instance with the service added.
public static IServiceCollection AddSaFileSystemFileStorage(
this IServiceCollection services,
Action configure)
diff --git a/src/Sa.HybridFileStorage.Postgres/FileIdParser.cs b/src/Sa.HybridFileStorage.Postgres/FileIdParser.cs
deleted file mode 100644
index 662cf157..00000000
--- a/src/Sa.HybridFileStorage.Postgres/FileIdParser.cs
+++ /dev/null
@@ -1,69 +0,0 @@
-using System.Globalization;
-
-namespace Sa.HybridFileStorage.Postgres;
-
-internal static class FileIdParser
-{
- public const string SchemeSeparator = "://";
-
- public static bool TryParse(
- string fileId,
- out string basket,
- out int tenantId,
- out long timestamp,
- out string fileName)
- {
- tenantId = default;
- timestamp = default;
- fileName = string.Empty;
- basket = string.Empty;
-
- if (string.IsNullOrEmpty(fileId)) return false;
-
- ReadOnlySpan span = fileId.AsSpan();
- int schemeEnd = span.IndexOf(SchemeSeparator.AsSpan());
- if (schemeEnd == -1) return false;
-
- var afterSpan = span[(schemeEnd + SchemeSeparator.Length)..];
- int scopeEnd = afterSpan.IndexOf('/');
- if (scopeEnd == -1) return false;
-
- basket = afterSpan[..scopeEnd].ToString();
-
- afterSpan = afterSpan[(scopeEnd + 1)..];
-
-
- int tenantEnd = afterSpan.IndexOf('/');
- if (tenantEnd == -1) return false;
-
- var tenantSpan = afterSpan[..tenantEnd];
- if (!int.TryParse(tenantSpan, NumberStyles.None, CultureInfo.InvariantCulture, out tenantId))
- return false;
-
- var afterTenant = afterSpan[(tenantEnd + 1)..];
- int timestampEnd = afterTenant.IndexOf('/');
- if (timestampEnd == -1) return false;
-
- var timestampSpan = afterTenant[..timestampEnd];
- if (!long.TryParse(timestampSpan, NumberStyles.None, CultureInfo.InvariantCulture, out timestamp))
- return false;
-
- fileName = afterTenant[(timestampEnd + 1)..].ToString();
- return !string.IsNullOrEmpty(fileName);
- }
-
-
- public static string FormatToFileId(
- string storageType,
- string basket,
- int tenantId,
- DateTimeOffset date,
- string fileName)
- => $"{storageType}://{basket}/{tenantId}/{date.ToUnixTimeSeconds()}/{NormalizeFileName(fileName)}";
-
- public static string NormalizeFileName(string fileName)
- => fileName.TrimStart('\\', '/').Replace('\\', '/');
-
- public static string GetFileExtension(string fileName)
- => Path.GetExtension(fileName ?? string.Empty).ToLower().TrimStart('.');
-}
diff --git a/src/Sa.HybridFileStorage.Postgres/IPostgresFileStorageConfiguration.cs b/src/Sa.HybridFileStorage.Postgres/IPostgresFileStorageConfiguration.cs
index bdf74c52..4b48b9b3 100644
--- a/src/Sa.HybridFileStorage.Postgres/IPostgresFileStorageConfiguration.cs
+++ b/src/Sa.HybridFileStorage.Postgres/IPostgresFileStorageConfiguration.cs
@@ -2,12 +2,49 @@
namespace Sa.HybridFileStorage.Postgres;
+///
+/// Defines a fluent configuration pipeline for the PostgreSQL file storage provider.
+///
public interface IPostgresFileStorageConfiguration
{
+ ///
+ /// Configures a custom PostgreSQL data source for connecting to the database.
+ ///
+ /// An optional action to configure the PostgreSQL data source settings builder.
+ /// The same instance for fluent chaining.
IPostgresFileStorageConfiguration AddDataSource(Action? configure = null);
+
+ ///
+ /// Configures the after the storage provider is registered.
+ ///
+ /// An action that receives an and for customization.
+ /// The same instance for fluent chaining.
IPostgresFileStorageConfiguration ConfigureOptions(Action configure);
+
+ ///
+ /// Sets the storage type identifier used in file IDs. Defaults to "pg".
+ ///
+ /// The storage type identifier.
+ /// The same instance for fluent chaining.
IPostgresFileStorageConfiguration WithStorageType(string storageType);
+
+ ///
+ /// Sets the database schema name where the files table resides. Defaults to "public".
+ ///
+ /// The database schema name.
+ /// The same instance for fluent chaining.
IPostgresFileStorageConfiguration WithSchemaName(string schemaName);
+
+ ///
+ /// Sets the database table name for storing file metadata. Defaults to "files".
+ ///
+ /// The database table name.
+ /// The same instance for fluent chaining.
IPostgresFileStorageConfiguration WithTableName(string tableName);
+
+ ///
+ /// Marks the PostgreSQL storage as read-only, preventing write operations.
+ ///
+ /// The same instance for fluent chaining.
IPostgresFileStorageConfiguration AsReadOnly();
}
diff --git a/src/Sa.HybridFileStorage.Postgres/PostgresFileStorage.cs b/src/Sa.HybridFileStorage.Postgres/PostgresFileStorage.cs
index 4f26e7bb..cc42291e 100644
--- a/src/Sa.HybridFileStorage.Postgres/PostgresFileStorage.cs
+++ b/src/Sa.HybridFileStorage.Postgres/PostgresFileStorage.cs
@@ -21,7 +21,7 @@ internal sealed class PostgresFileStorage(
private const string InsertSql =
"""
- INSERT INTO {0} (id, name, file_ext, data, size, tenant_id, basket, created_at)
+ INSERT INTO {0} (id, name, file_ext, data, size, tenant_id, basket, created_at)
VALUES (@id, @name, @file_ext, @data, @size, @tenant_id, @basket, @created_at)
ON CONFLICT (id, tenant_id, basket, created_at) DO UPDATE SET
data = EXCLUDED.data,
@@ -50,7 +50,7 @@ private readonly string _qualifiedTableName
= $"{options.SchemaName}.\"{Sanitize(options.TableName)}\"";
private readonly string _schemePrefix
- = $"{options.StorageType}{FileIdParser.SchemeSeparator}{options.TableName}/";
+ = $"{options.StorageType}{FileIdParser.SchemeSeparator}{Sanitize(basket)}/";
private readonly TimeProvider _timeProvider = timeProvider ?? TimeProvider.System;
@@ -75,8 +75,8 @@ public bool CanProcess(string? fileId)
{
var fileSpan = fileId.AsSpan();
- if (!string.IsNullOrWhiteSpace(fileId)
- && fileSpan.StartsWith(_schemePrefix.AsSpan(), StringComparison.Ordinal)) return false;
+ if (string.IsNullOrWhiteSpace(fileId)
+ || !fileSpan.StartsWith(_schemePrefix.AsSpan(), StringComparison.Ordinal)) return false;
int schemeEnd = fileSpan.IndexOf(FileIdParser.SchemeSeparator.AsSpan());
if (schemeEnd == -1) return false;
@@ -96,6 +96,9 @@ public async Task UploadAsync(
CancellationToken cancellationToken)
{
EnsureWritable();
+ ArgumentNullException.ThrowIfNull(fileStream);
+
+ metadata.Validate();
DateTimeOffset createdAtDay = _timeProvider.GetUtcNow().Date;
long createdAt = createdAtDay.ToUnixTimeSeconds();
@@ -105,22 +108,24 @@ await partManager.EnsureParts(
_qualifiedTableName,
createdAtDay,
[metadata.TenantId, _partName],
- cancellationToken);
+ cancellationToken).ConfigureAwait(false);
string fileId = FileIdParser.FormatToFileId(
StorageType, _partName, metadata.TenantId, createdAtDay, metadata.FileName);
string fileExtension = FileIdParser.GetFileExtension(metadata.FileName);
+ // If stream isn't seekable, copy into a recyclable MemoryStream first
Stream ms = fileStream;
+ bool ownsMs = false;
- if (!fileStream.CanSeek) // fileStream is not MemoryStream ms)
+ if (!fileStream.CanSeek)
{
ms = streamManager.GetStream();
- await fileStream.CopyToAsync(ms, cancellationToken);
+ await fileStream.CopyToAsync(ms, cancellationToken).ConfigureAwait(false);
+ ownsMs = true;
}
-
- if (fileStream.CanSeek) // fileStream is not MemoryStream ms)
+ else
{
ms.Position = 0;
}
@@ -139,13 +144,14 @@ await dataSource.ExecuteNonQuery(sql,
, new NpgsqlParameter("tenant_id", metadata.TenantId)
, new NpgsqlParameter("basket", _partName)
, new NpgsqlParameter("created_at", createdAt)
- ], cancellationToken);
+ ], cancellationToken).ConfigureAwait(false);
}
finally
{
- if (ms != fileStream)
+ // Only dispose the buffer we allocated — never dispose the caller's stream
+ if (ownsMs)
{
- await ms.DisposeAsync();
+ await ms.DisposeAsync().ConfigureAwait(false);
}
}
@@ -156,6 +162,11 @@ public async Task DeleteAsync(string fileId, CancellationToken cancellatio
{
EnsureWritable();
+
+ if (!CanProcess(fileId))
+ return false;
+
+
if (!FileIdParser.TryParse(fileId, out _, out int tenantId, out long timestamp, out _))
{
return false;
@@ -170,7 +181,7 @@ public async Task DeleteAsync(string fileId, CancellationToken cancellatio
new NpgsqlParameter("basket", _partName),
new NpgsqlParameter("timestamp", timestamp),
new NpgsqlParameter("id", fileId)
- ], cancellationToken);
+ ], cancellationToken).ConfigureAwait(false);
return rowsAffected > 0;
}
@@ -180,6 +191,11 @@ public async Task DownloadAsync(
Func loadStream,
CancellationToken cancellationToken)
{
+
+
+ if (!CanProcess(fileId))
+ return false;
+
if (!FileIdParser.TryParse(fileId, out _, out int tenantId, out long timestamp, out _))
{
return false;
@@ -189,15 +205,15 @@ public async Task DownloadAsync(
int rowsAffected = await dataSource.ExecuteReader(sql, async (reader, i) =>
{
- using var fs = await reader.GetStreamAsync(0, cancellationToken);
- await loadStream(fs, cancellationToken);
+ using var fs = await reader.GetStreamAsync(0, cancellationToken).ConfigureAwait(false);
+ await loadStream(fs, cancellationToken).ConfigureAwait(false);
},
[
new NpgsqlParameter("tenant_id", tenantId),
new NpgsqlParameter("basket", _partName),
new NpgsqlParameter("timestamp", timestamp),
new NpgsqlParameter("id", fileId)
- ], cancellationToken);
+ ], cancellationToken).ConfigureAwait(false);
return rowsAffected > 0;
}
diff --git a/src/Sa.HybridFileStorage.Postgres/PostgresFileStorageOptions.cs b/src/Sa.HybridFileStorage.Postgres/PostgresFileStorageOptions.cs
index 34244c3a..053eecda 100644
--- a/src/Sa.HybridFileStorage.Postgres/PostgresFileStorageOptions.cs
+++ b/src/Sa.HybridFileStorage.Postgres/PostgresFileStorageOptions.cs
@@ -2,29 +2,81 @@
namespace Sa.HybridFileStorage.Postgres;
+///
+/// Configuration options for the PostgreSQL storage engine (schema, table, read-only mode).
+///
public sealed record StorageOptions
{
+ ///
+ /// Gets or sets the database schema name. Defaults to "public".
+ ///
public string SchemaName { get; set; } = "public";
+
+ ///
+ /// Gets or sets the database table name for storing file metadata. Defaults to "files".
+ ///
public string TableName { get; set; } = "files";
+
+ ///
+ /// Gets or sets the storage type identifier. Defaults to "pg".
+ ///
public string StorageType { get; set; } = "pg";
+
+ ///
+ /// Gets or sets a value indicating whether this storage is read-only. Defaults to false.
+ ///
public bool IsReadOnly { get; set; }
}
+///
+/// Configuration options for automatic cleanup of expired file records.
+///
public sealed class CleanupOptions
{
+ ///
+ /// Gets or sets the number of days after which file records are considered expired and eligible for cleanup. Defaults to 1095 (3 years).
+ ///
public int ExpireDays { get; set; } = 365 * 3;
}
+///
+/// Configuration options for PostgreSQL table partitioning.
+///
public sealed class PartOptions
{
+ ///
+ /// Gets or sets the number of days in advance to generate the migration schedule for new partitions. Defaults to 2.
+ ///
public int MigrationScheduleForwardDays { get; set; } = 2;
+
+ ///
+ /// Gets or sets the partitioning granularity (day, month, or year). Defaults to .
+ ///
public PgPartBy PgPartBy { get; set; } = PgPartBy.Day;
+
+ ///
+ /// Gets or sets the basket (container) name. Defaults to "share".
+ ///
public string Basket { get; set; } = "share";
}
+///
+/// Aggregates all configuration options for the PostgreSQL file storage provider.
+///
public sealed class PostgresFileStorageOptions
{
+ ///
+ /// Gets the storage-specific options (schema, table, type, read-only mode).
+ ///
public StorageOptions StorageOptions { get; } = new();
+
+ ///
+ /// Gets the partitioning options.
+ ///
public PartOptions PartOptions { get; } = new();
+
+ ///
+ /// Gets the cleanup options.
+ ///
public CleanupOptions CleanupOptions { get; } = new();
}
diff --git a/src/Sa.HybridFileStorage.Postgres/README.md b/src/Sa.HybridFileStorage.Postgres/README.md
new file mode 100644
index 00000000..2382e1be
--- /dev/null
+++ b/src/Sa.HybridFileStorage.Postgres/README.md
@@ -0,0 +1,316 @@
+# Sa.HybridFileStorage.Postgres
+
+PostgreSQL-backed file storage provider for `Sa.HybridFileStorage`. Stores files as `BYTEA` in a partitioned database table with automatic partition management, scheduled migration, and background cleanup.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [File ID Format](#file-id-format)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+ - [Without DI](#without-di)
+ - [With DI](#with-di)
+- [CRUD Examples](#crud-examples)
+- [Partitioning](#partitioning)
+- [Scheduled Maintenance](#scheduled-maintenance)
+- [Settings Reference](#settings-reference)
+- [Dependencies](#dependencies)
+
+---
+
+## Overview
+
+`PostgresFileStorage` implements `IFileStorage` backed by PostgreSQL. File binary data is stored as `BYTEA` columns in a partitioned table. Key characteristics:
+
+- **Automatic partitioning** — declarative list + range partitioning via `Sa.Partitional.PostgreSql`
+- **Upsert semantics** — `ON CONFLICT DO UPDATE` handles re-uploads transparently
+- **Scheduled migrations** — background job pre-creates future partitions
+- **Background cleanup** — drops old partitions beyond retention period
+- **Non-seekable stream handling** — buffers unseekable streams into `RecyclableMemoryStreamManager`
+- **Timestamp in File ID** — includes Unix seconds for range partition resolution
+
+---
+
+## File ID Format
+
+```
+pg://{basket}/{tenantId}/{unixTimestamp}/{fileName}
+```
+
+**Examples:**
+- `pg://files/42/1751347200/report.pdf`
+- `pg://docs/7/1751347200/invoice.csv`
+- `pg://share/100/1751347200/data.bin`
+
+> The timestamp is the Unix epoch seconds of the upload date (UTC midnight). It determines which partition the row belongs to.
+
+---
+
+## Installation
+
+```powershell
+dotnet add package Sa.HybridFileStorage.Postgres
+```
+
+This package depends on `Sa.Data.PostgreSql` and `Sa.Partitional.PostgreSql`.
+
+---
+
+## Quick Start
+
+### Without DI
+
+```csharp
+using Sa.HybridFileStorage.Postgres;
+using Sa.HybridFileStorage.Domain;
+
+// Configure via fluent builder
+var configurator = new PostgresFileStorageConfiguration(services);
+
+// Or register through DI extension
+builder.Services.AddSaPostgreSqlFileStorage(cfg => cfg
+ .AddDataSource(ds => ds
+ .WithConnectionString("Host=localhost;Database=mydb;Username=postgres;Password=password")
+ .WithSearchPath("public"))
+ .WithSchemaName("public")
+ .WithTableName("files")
+ .WithStorageType("pg")
+ .ConfigureOptions((sp, options) =>
+ {
+ // Customize partitioning
+ options.PartOptions.Basket = "files";
+ options.PartOptions.PgPartBy = PgPartBy.Day;
+ options.PartOptions.MigrationScheduleForwardDays = 2;
+
+ // Customize cleanup
+ options.CleanupOptions.ExpireDays = 365 * 3; // 3 years
+ }));
+```
+
+### With DI
+
+```csharp
+using Sa.HybridFileStorage.Postgres;
+
+builder.Services.AddSaPostgreSqlFileStorage(cfg => cfg
+ .AddDataSource(ds => ds
+ .WithConnectionString("Host=db.example.com;Database=app;Username=app_user;Password=secret")
+ .WithSearchPath("storage"))
+ .WithTableName("binary_data")
+ .WithSchemaName("storage")
+ .ConfigureOptions((sp, opts) =>
+ {
+ opts.PartOptions.Basket = "attachments";
+ opts.PartOptions.PgPartBy = PgPartBy.Month;
+ opts.CleanupOptions.ExpireDays = 730; // 2 years
+ }));
+```
+
+---
+
+## CRUD Examples
+
+### Upload from Stream
+
+```csharp
+using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, Postgres!"));
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "hello.txt", TenantId = 42 },
+ stream, ct);
+
+Console.WriteLine(result.FileId);
+// pg://files/42/1751347200/hello.txt
+// (timestamp = today's UTC midnight as Unix seconds)
+```
+
+### Upload Non-Seekable Stream
+
+```csharp
+// Non-seekable streams are automatically buffered into RecyclableMemoryStreamManager
+await using var nonSeekable = CreateNonSeekableStream();
+
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "blob.dat", TenantId = 7 },
+ nonSeekable, ct);
+
+// Internally: copied → buffered → upserted → buffer recycled
+```
+
+### Download to Memory
+
+```csharp
+byte[]? downloaded = default;
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ downloaded = await stream.ReadAllBytesAsync(token);
+}, ct);
+```
+
+### Download Direct Processing
+
+```csharp
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ // Process stream directly — no intermediate buffering
+ using var reader = new BinaryReader(stream);
+ while (reader.ReadByte() is byte b)
+ {
+ // ...
+ }
+}, ct);
+```
+
+### Get Metadata
+
+```csharp
+var metadata = await storage.GetMetadataAsync(result.FileId, ct);
+if (metadata != null)
+{
+ Console.WriteLine($"Корзина: {metadata.Basket}"); // files
+ Console.WriteLine($"Тенант: {metadata.TenantId}"); // 42
+ Console.WriteLine($"Имя: {metadata.FileName}"); // hello.txt
+ Console.WriteLine($"Тип: {metadata.StorageType}"); // pg
+}
+```
+
+### Delete
+
+```csharp
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+// Parses tenantId and timestamp from File ID for targeted DELETE
+```
+
+---
+
+## Partitioning
+
+Files are stored in a partitioned table with dual partitioning strategy:
+
+1. **List partitioning** — by `(tenant_id, basket)` tuple
+2. **Range partitioning** — by `created_at` (date)
+
+### Schema auto-creation
+
+The provider uses `Sa.Partitional.PostgreSql` to manage partitions:
+
+```sql
+-- Auto-created table structure:
+CREATE TABLE public.files (
+ id TEXT NOT NULL,
+ name TEXT NOT NULL,
+ size INT NOT NULL,
+ file_ext TEXT NOT NULL,
+ tenant_id INT NOT NULL,
+ basket TEXT NOT NULL,
+ data BYTEA NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL -- used for range partitioning
+) PARTITION BY RANGE (created_at);
+
+-- Each (tenant_id, basket) pair gets its own list partition within each date range
+```
+
+### Partition strategies
+
+| Strategy | `PgPartBy` value | Use case |
+|----------|------------------|----------|
+| Day | `PgPartBy.Day` | High-volume systems, fine-grained cleanup |
+| Month | `PgPartBy.Month` | Medium volume, balanced granularity |
+| Year | `PgPartBy.Year` | Low volume, simple management |
+
+### Migration schedule
+
+New partitions are pre-created in advance (default: 2 days ahead) via a background job:
+
+```csharp
+.ConfigureOptions((sp, opts) =>
+{
+ opts.PartOptions.MigrationScheduleForwardDays = 2;
+})
+```
+
+### Cleanup schedule
+
+Old partitions beyond the retention period are dropped via a background job:
+
+```csharp
+.ConfigureOptions((sp, opts) =>
+{
+ opts.CleanupOptions.ExpireDays = 365 * 3; // drop partitions older than 3 years
+})
+```
+
+---
+
+## Scheduled Maintenance
+
+Two background jobs are registered automatically:
+
+| Job | Purpose | Configuration |
+|-----|---------|--------------|
+| **Migration** | Pre-create upcoming partitions | `forwardDays`, `asBackgroundJob` |
+| **Cleanup** | Drop old partitions after retention | `dropPartsAfterRetention` (TimeSpan) |
+
+Both run as background hosted services and use the same PostgreSQL connection pool.
+
+---
+
+## Settings Reference
+
+### PostgresFileStorageOptions
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `StorageOptions.SchemaName` | PostgreSQL schema | `"public"` |
+| `StorageOptions.TableName` | Table name for file data | `"files"` |
+| `StorageOptions.StorageType` | Scheme prefix in File ID | `"pg"` |
+| `StorageOptions.IsReadOnly` | Prevent write/delete operations | `false` |
+| `PartOptions.Basket` | Scope/container name (used as list partition key) | `"share"` |
+| `PartOptions.PgPartBy` | Range partitioning granularity | `PgPartBy.Day` |
+| `PartOptions.MigrationScheduleForwardDays` | Days ahead to pre-create partitions | `2` |
+| `CleanupOptions.ExpireDays` | Retention period before partition drop (days) | `365 * 3` |
+
+### IPostgresFileStorageConfiguration (fluent builder)
+
+| Method | Description |
+|--------|-------------|
+| `AddDataSource(Action?)` | Configure PostgreSQL connection |
+| `WithSchemaName(string)` | Override schema name |
+| `WithTableName(string)` | Override table name |
+| `WithStorageType(string)` | Override storage type identifier |
+| `AsReadOnly()` | Mark as read-only |
+| `ConfigureOptions(Action)` | Late-stage customization |
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `Sa.Data.PostgreSql` | Npgsql client (`IPgDataSource`) |
+| `Sa.Partitional.PostgreSql` | Declarative partition management (`IPartitionManager`) |
+| `Microsoft.IO.RecyclableMemoryStream` | Efficient memory buffering for non-seekable streams |
+
+---
+
+## Data Model
+
+The underlying table structure:
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `id` | `TEXT` | Canonical File ID (primary key part) |
+| `name` | `TEXT` | Original file name |
+| `size` | `INT` | File size in bytes |
+| `file_ext` | `TEXT` | File extension (e.g., "pdf", "png") |
+| `tenant_id` | `INT` | Tenant identifier (list partition key) |
+| `basket` | `TEXT` | Container/scope name (list partition key) |
+| `data` | `BYTEA` | Raw file binary content |
+| `created_at` | `TIMESTAMPTZ` | Upload date (UTC midnight, range partition key) |
+
+---
+
+## License
+
+MIT
diff --git a/src/Sa.HybridFileStorage.Postgres/Readme-ru.md b/src/Sa.HybridFileStorage.Postgres/Readme-ru.md
new file mode 100644
index 00000000..13ae5ff2
--- /dev/null
+++ b/src/Sa.HybridFileStorage.Postgres/Readme-ru.md
@@ -0,0 +1,311 @@
+# Sa.HybridFileStorage.Postgres
+
+Провайдер файловых хранилищ на базе PostgreSQL для `Sa.HybridFileStorage`. Хранит файлы как `BYTEA` в партиционированной таблице с автоматическим управлением партициями, запланированной миграцией и фоновой очисткой.
+
+---
+
+## Содержание
+
+- [Обзор](#обзор)
+- [Формат File ID](#формат-file-id)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+ - [Без DI](#без-di)
+ - [С DI](#с-di)
+- [Примеры CRUD](#примеры-crud)
+- [Партиционирование](#партиционирование)
+- [Запланированное обслуживание](#запланированное-обслуживание)
+- [Справочник настроек](#справочник-настроек)
+- [Зависимости](#зависимости)
+
+---
+
+## Обзор
+
+`PostgresFileStorage` реализует `IFileStorage` поверх PostgreSQL. Бинарные данные файлов хранятся в колонке `BYTEA` партиционированной таблицы. Ключевые особенности:
+
+- **Автоматическое партиционирование** — декларативное list + range партиционирование через `Sa.Partitional.PostgreSql`
+- **Upsert-семантика** — `ON CONFLICT DO UPDATE` прозрачно обрабатывает повторные загрузки
+- **Запланированная миграция** — фоновое задание заранее создаёт будущие партиции
+- **Фоновая очистка** — удаляет старые партиции за пределами периода удержания
+- **Обработка не-seekable потоков** — буферизует не-seekable потоки через `RecyclableMemoryStreamManager`
+- **Таймстамп в File ID** — включает Unix-секунды для разрешения range-партиций
+
+---
+
+## Формат File ID
+
+```
+pg://{basket}/{tenantId}/{unixTimestamp}/{fileName}
+```
+
+**Примеры:**
+- `pg://files/42/1751347200/report.pdf`
+- `pg://docs/7/1751347200/invoice.csv`
+- `pg://share/100/1751347200/data.bin`
+
+> Таймстамп — это Unix-секунды полуночи UTC даты загрузки. Он определяет, к какой партиции относится строка.
+
+---
+
+## Установка
+
+```powershell
+dotnet add package Sa.HybridFileStorage.Postgres
+```
+
+---
+
+## Быстрый старт
+
+### Без DI
+
+```csharp
+using Sa.HybridFileStorage.Postgres;
+using Sa.HybridFileStorage.Domain;
+
+// Регистрация через fluent builder
+builder.Services.AddSaPostgreSqlFileStorage(cfg => cfg
+ .AddDataSource(ds => ds
+ .WithConnectionString("Host=localhost;Database=mydb;Username=postgres;Password=password")
+ .WithSearchPath("public"))
+ .WithSchemaName("public")
+ .WithTableName("files")
+ .WithStorageType("pg")
+ .ConfigureOptions((sp, options) =>
+ {
+ // Настройка партиционирования
+ options.PartOptions.Basket = "files";
+ options.PartOptions.PgPartBy = PgPartBy.Day;
+ options.PartOptions.MigrationScheduleForwardDays = 2;
+
+ // Настройка очистки
+ options.CleanupOptions.ExpireDays = 365 * 3; // 3 года
+ }));
+```
+
+### С DI
+
+```csharp
+using Sa.HybridFileStorage.Postgres;
+
+builder.Services.AddSaPostgreSqlFileStorage(cfg => cfg
+ .AddDataSource(ds => ds
+ .WithConnectionString("Host=db.example.com;Database=app;Username=app_user;Password=secret")
+ .WithSearchPath("storage"))
+ .WithTableName("binary_data")
+ .WithSchemaName("storage")
+ .ConfigureOptions((sp, opts) =>
+ {
+ opts.PartOptions.Basket = "attachments";
+ opts.PartOptions.PgPartBy = PgPartBy.Month;
+ opts.CleanupOptions.ExpireDays = 730; // 2 года
+ }));
+```
+
+---
+
+## Примеры CRUD
+
+### Загрузка из Stream
+
+```csharp
+using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, Postgres!"));
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "hello.txt", TenantId = 42 },
+ stream, ct);
+
+Console.WriteLine(result.FileId);
+// pg://files/42/1751347200/hello.txt
+// (timestamp = полуночь UTC сегодняшнего дня в Unix-секундах)
+```
+
+### Загрузка не-seekable потока
+
+```csharp
+// Не-seekable потоки автоматически буферизуются в RecyclableMemoryStreamManager
+await using var nonSeekable = CreateNonSeekableStream();
+
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "blob.dat", TenantId = 7 },
+ nonSeekable, ct);
+
+// Внутренне: скопирован → буферизован → upsert → буфер перезапущен
+```
+
+### Скачивание в память
+
+```csharp
+byte[]? downloaded = default;
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ downloaded = await stream.ReadAllBytesAsync(token);
+}, ct);
+```
+
+### Прямая обработка при скачивании
+
+```csharp
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ // Обрабатываем поток напрямую — без промежуточной буферизации
+ using var reader = new BinaryReader(stream);
+ while (reader.ReadByte() is byte b)
+ {
+ // ...
+ }
+}, ct);
+```
+
+### Получение метаданных
+
+```csharp
+var metadata = await storage.GetMetadataAsync(result.FileId, ct);
+if (metadata != null)
+{
+ Console.WriteLine($"Корзина: {metadata.Basket}"); // files
+ Console.WriteLine($"Тенант: {metadata.TenantId}"); // 42
+ Console.WriteLine($"Имя: {metadata.FileName}"); // hello.txt
+ Console.WriteLine($"Тип: {metadata.StorageType}"); // pg
+}
+```
+
+### Удаление
+
+```csharp
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+// Парсит tenantId и timestamp из File ID для таргетированного DELETE
+```
+
+---
+
+## Партиционирование
+
+Файлы хранятся в партиционированной таблице с двойной стратегией:
+
+1. **List-партиционирование** — по кортежу `(tenant_id, basket)`
+2. **Range-партиционирование** — по `created_at` (дата)
+
+### Авто-создание схемы
+
+Провайдер использует `Sa.Partitional.PostgreSql` для управления партициями:
+
+```sql
+-- Автоматически созданная структура таблицы:
+CREATE TABLE public.files (
+ id TEXT NOT NULL,
+ name TEXT NOT NULL,
+ size INT NOT NULL,
+ file_ext TEXT NOT NULL,
+ tenant_id INT NOT NULL,
+ basket TEXT NOT NULL,
+ data BYTEA NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL -- используется для range-партиционирования
+) PARTITION BY RANGE (created_at);
+
+-- Каждая пара (tenant_id, basket) получает собственную list-партию внутри каждого диапазона дат
+```
+
+### Стратегии партиционирования
+
+| Стратегия | Значение `PgPartBy` | Сценарий использования |
+|-----------|---------------------|----------------------|
+| День | `PgPartBy.Day` | Высоконагруженные системы, тонкая очистка |
+| Месяц | `PgPartBy.Month` | Средняя нагрузка, сбалансированная гранулярность |
+| Год | `PgPartBy.Year` | Низкая нагрузка, простое управление |
+
+### Расписание миграции
+
+Новые партиции создаются заранее (по умолчанию: за 2 дня) через фоновое задание:
+
+```csharp
+.ConfigureOptions((sp, opts) =>
+{
+ opts.PartOptions.MigrationScheduleForwardDays = 2;
+})
+```
+
+### Расписание очистки
+
+Старые партиции за пределами периода удержания удаляются через фоновое задание:
+
+```csharp
+.ConfigureOptions((sp, opts) =>
+{
+ opts.CleanupOptions.ExpireDays = 365 * 3; // удалять партиции старше 3 лет
+})
+```
+
+---
+
+## Запланированное обслуживание
+
+Автоматически регистрируются два фоновых задания:
+
+| Задание | Назначение | Конфигурация |
+|---------|-----------|-------------|
+| **Миграция** | Заранее создавать будущие партиции | `forwardDays`, `asBackgroundJob` |
+| **Очистка** | Удалять старые партиции после истечения срока | `dropPartsAfterRetention` (TimeSpan) |
+
+Оба работают как фоновые hosted-сервисы и используют общий пул подключений PostgreSQL.
+
+---
+
+## Справочник настроек
+
+### PostgresFileStorageOptions
+
+| Свойство | Описание | По умолчанию |
+|----------|----------|-------------|
+| `StorageOptions.SchemaName` | Схема PostgreSQL | `"public"` |
+| `StorageOptions.TableName` | Имя таблицы для данных файлов | `"files"` |
+| `StorageOptions.StorageType` | Префикс схемы в File ID | `"pg"` |
+| `StorageOptions.IsReadOnly` | Запрет операций записи/удаления | `false` |
+| `PartOptions.Basket` | Имя контейнера (ключ list-партиции) | `"share"` |
+| `PartOptions.PgPartBy` | Гранулярность range-партиционирования | `PgPartBy.Day` |
+| `PartOptions.MigrationScheduleForwardDays` | Дней заранее для предсоздания партиций | `2` |
+| `CleanupOptions.ExpireDays` | Период удержания перед удалением партиции (дни) | `365 * 3` |
+
+### IPostgresFileStorageConfiguration (fluent builder)
+
+| Метод | Описание |
+|-------|----------|
+| `AddDataSource(Action?)` | Настроить подключение PostgreSQL |
+| `WithSchemaName(string)` | Переопределить имя схемы |
+| `WithTableName(string)` | Переопределить имя таблицы |
+| `WithStorageType(string)` | Переопределить идентификатор типа хранилища |
+| `AsReadOnly()` | Пометить как read-only |
+| `ConfigureOptions(Action)` | Поздняя кастомизация |
+
+---
+
+## Зависимости
+
+| Пакет | Назначение |
+|-------|-----------|
+| `Sa.Data.PostgreSql` | Npgsql клиент (`IPgDataSource`) |
+| `Sa.Partitional.PostgreSql` | Управление партициями (`IPartitionManager`) |
+| `Microsoft.IO.RecyclableMemoryStream` | Эффективная буферизация памяти для не-seekable потоков |
+
+---
+
+## Модель данных
+
+Структура базовой таблицы:
+
+| Колонка | Тип | Назначение |
+|---------|-----|-----------|
+| `id` | `TEXT` | Канонический File ID (часть первичного ключа) |
+| `name` | `TEXT` | Оригинальное имя файла |
+| `size` | `INT` | Размер файла в байтах |
+| `file_ext` | `TEXT` | Расширение файла (напр., "pdf", "png") |
+| `tenant_id` | `INT` | Идентификатор тенанта (ключ list-партиции) |
+| `basket` | `TEXT` | Имя контейнера (ключ list-партиции) |
+| `data` | `BYTEA` | Сырые бинарные данные файла |
+| `created_at` | `TIMESTAMPTZ` | Дата загрузки (полуночь UTC, ключ range-партиции) |
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.HybridFileStorage.Postgres/Sa.HybridFileStorage.Postgres.csproj b/src/Sa.HybridFileStorage.Postgres/Sa.HybridFileStorage.Postgres.csproj
index 4bb00065..e517a8ec 100644
--- a/src/Sa.HybridFileStorage.Postgres/Sa.HybridFileStorage.Postgres.csproj
+++ b/src/Sa.HybridFileStorage.Postgres/Sa.HybridFileStorage.Postgres.csproj
@@ -3,7 +3,7 @@
- 0.9.1
+ 0.10.0
File storage management in Pg
diff --git a/src/Sa.HybridFileStorage.Postgres/Setup.cs b/src/Sa.HybridFileStorage.Postgres/Setup.cs
index e441bbde..732ae8b2 100644
--- a/src/Sa.HybridFileStorage.Postgres/Setup.cs
+++ b/src/Sa.HybridFileStorage.Postgres/Setup.cs
@@ -2,9 +2,17 @@
namespace Sa.HybridFileStorage.Postgres;
-
+///
+/// Provides extension methods for registering the PostgreSQL file storage provider with the .NET Generic Host.
+///
public static class Setup
{
+ ///
+ /// Registers the PostgreSQL file storage provider with the specified service collection.
+ ///
+ /// The service collection to add the services to.
+ /// An optional action to configure the PostgreSQL storage via .
+ /// The same instance with the services added.
public static IServiceCollection AddSaPostgreSqlFileStorage(
this IServiceCollection services,
Action? configure = null)
diff --git a/src/Sa.HybridFileStorage.S3/README.md b/src/Sa.HybridFileStorage.S3/README.md
new file mode 100644
index 00000000..d1f2c4cb
--- /dev/null
+++ b/src/Sa.HybridFileStorage.S3/README.md
@@ -0,0 +1,231 @@
+# Sa.HybridFileStorage.S3
+
+S3-compatible cloud storage provider for `Sa.HybridFileStorage`. Wraps Minio/AWS S3 with automatic bucket creation, MIME type detection, and streaming file I/O.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [File ID Format](#file-id-format)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+ - [Without DI](#without-di)
+ - [With DI](#with-di)
+- [CRUD Examples](#crud-examples)
+- [Settings Reference](#settings-reference)
+- [Dependencies](#dependencies)
+
+---
+
+## Overview
+
+`S3FileStorage` implements `IFileStorage` backed by any S3-compatible service (AWS S3, MinIO, DigitalOcean Spaces, etc.). Key characteristics:
+
+- **Auto bucket creation** — creates the target bucket on first upload if it doesn't exist (thread-safe, single-flight)
+- **MIME type detection** — resolves content type from file extension using `MimeTypeMap`
+- **Streaming uploads/downloads** — uses `IS3BucketClient` for memory-efficient transfers
+- **Thread-safe initialization** — concurrent `EnsureBucket` calls are deduplicated via `Interlocked.CompareExchange`
+
+---
+
+## File ID Format
+
+```
+s3://{basket}/{tenantId}/{fileName}
+```
+
+**Examples:**
+- `s3://uploads/42/document.pdf`
+- `s3://avatars/7/profile.png`
+- `s3://backups/100/database.sql`
+
+---
+
+## Installation
+
+```powershell
+dotnet add package Sa.HybridFileStorage.S3
+```
+
+This package depends on `Sa.Data.S3` which provides the underlying `IS3BucketClient`.
+
+---
+
+## Quick Start
+
+### Without DI
+
+```csharp
+using Sa.HybridFileStorage.S3;
+using Sa.HybridFileStorage.Domain;
+using Sa.Data.S3;
+
+// Configure S3 client
+var setup = new S3BucketClientSetupSettings
+{
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ Bucket = "mybucket",
+ Region = "us-east-1"
+};
+
+var client = new S3BucketClient(setup);
+
+var options = new S3FileStorageOptions
+{
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ Bucket = "mybucket",
+ Basket = "uploads",
+ Region = "us-east-1"
+};
+
+using var storage = new S3FileStorage(client, options);
+
+// Upload
+using var stream = File.OpenRead(@"C:\temp\document.pdf");
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "document.pdf", TenantId = 42 },
+ stream, ct);
+
+Console.WriteLine(result.FileId); // s3://uploads/42/document.pdf
+Console.WriteLine(result.AbsoluteUrl); // http://localhost:9000/mybucket/uploads/42/document.pdf
+
+// Download
+bool found = await storage.DownloadAsync(result.FileId, async (fs, token) =>
+{
+ using var reader = new StreamReader(fs, Encoding.UTF8);
+ var content = await reader.ReadToEndAsync(token);
+ Console.WriteLine(content);
+}, ct);
+
+// Delete
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+```
+
+### With DI
+
+```csharp
+using Sa.HybridFileStorage.S3;
+
+builder.Services.AddSaS3FileStorage(new S3FileStorageOptions
+{
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ Bucket = "mybucket",
+ Basket = "uploads",
+ Region = "us-east-1"
+});
+
+// The DI container resolves IS3BucketClient automatically
+```
+
+---
+
+## CRUD Examples
+
+### Upload from Stream
+
+```csharp
+using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, S3!"));
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "hello.txt", TenantId = 1 },
+ stream, ct);
+
+// File stored at: mybucket/uploads/1/hello.txt
+// Content-Type: text/plain (auto-detected from extension)
+```
+
+### Upload Large Files
+
+```csharp
+// Streaming large files without loading into memory
+await using var fs = new FileStream(@"C:\large\data.zip", new FileStreamOptions
+{
+ Mode = FileMode.Open,
+ Access = FileAccess.Read,
+ Share = FileShare.Read,
+ Options = FileOptions.Asynchronous | FileOptions.SequentialScan
+});
+
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "data.zip", TenantId = 5 },
+ fs, ct);
+```
+
+### Download to Memory
+
+```csharp
+byte[]? downloaded = default;
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ downloaded = await stream.ReadAllBytesAsync(token);
+}, ct);
+```
+
+### Download to Disk
+
+```csharp
+await using var destination = new FileStream(@"C:\output\downloaded.pdf", FileMode.Create);
+await storage.DownloadAsync(result.FileId, async (source, token) =>
+ await source.CopyToAsync(destination, 1024 * 1024, token), // 1 MB buffer
+ ct);
+```
+
+### Get Metadata
+
+```csharp
+var metadata = await storage.GetMetadataAsync(result.FileId, ct);
+if (metadata != null)
+{
+ Console.WriteLine($"Basket: {metadata.Basket}"); // uploads
+ Console.WriteLine($"Tenant: {metadata.TenantId}"); // 42
+ Console.WriteLine($"Name: {metadata.FileName}"); // document.pdf
+ Console.WriteLine($"Type: {metadata.StorageType}"); // s3
+}
+```
+
+### Delete
+
+```csharp
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+// Always returns true if CanProcess(fileId) == true — S3 deletes silently ignore missing objects
+```
+
+---
+
+## Settings Reference
+
+### S3FileStorageOptions
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `Endpoint` | S3-compatible endpoint URL | *(required)* |
+| `AccessKey` | Access key ID | *(required)* |
+| `SecretKey` | Secret access key | *(required)* |
+| `Bucket` | Target bucket name | *(required)* |
+| `Basket` | Scope/container prefix within the bucket | `"share"` |
+| `Region` | AWS region for SigV4 signing | `"eu-central-1"` |
+| `StorageType` | Scheme prefix in File ID | `"s3"` |
+| `IsReadOnly` | Prevent write/delete operations | `false` |
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `Sa.Data.S3` | S3 client (`IS3BucketClient`, `S3BucketClient`) |
+| `Sa` | Shared utilities (`MimeTypeMap`) |
+
+The `AddSaS3FileStorage` extension method automatically registers `IS3BucketClient` via `AddSaS3BucketClient`.
+
+---
+
+## License
+
+MIT
diff --git a/src/Sa.HybridFileStorage.S3/Readme-ru.md b/src/Sa.HybridFileStorage.S3/Readme-ru.md
new file mode 100644
index 00000000..01fc1fc8
--- /dev/null
+++ b/src/Sa.HybridFileStorage.S3/Readme-ru.md
@@ -0,0 +1,218 @@
+# Sa.HybridFileStorage.S3
+
+Провайдер S3-совместимого облачного хранилища для `Sa.HybridFileStorage`. Использует `Sa.Data.S3` клиент с автосозданием бакета, автоопределением MIME-типов и SigV4 подписью.
+
+---
+
+## Содержание
+
+- [Обзор](#обзор)
+- [Формат File ID](#формат-file-id)
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+ - [Без DI](#без-di)
+ - [С DI](#с-di)
+- [Примеры CRUD](#примеры-crud)
+- [Справочник настроек](#справочник-настроек)
+- [Зависимости](#зависимости)
+
+---
+
+## Обзор
+
+`S3FileStorage` реализует `IFileStorage` поверх S3-совместимых хранилищ (AWS S3, MinIO, DigitalOcean Spaces и др.). Файлы хранятся в бакете по структуре:
+
+```
+{Bucket}/{Basket}/{TenantId}/{FileName}
+```
+
+Ключевые особенности:
+- **Автосоздание бакета** — если бакет не существует, создаётся при первой загрузке (потокобезопасно через `Interlocked.CompareExchange`)
+- **Авто-MIME** — определяет `Content-Type` из расширения файла через `MimeTypeMap`
+- **SigV4 подпись** — поддерживает AWS Signature Version 4
+- **Потоковая передача** — потоки копируются напрямую без промежуточных буферов
+
+---
+
+## Формат File ID
+
+```
+s3://{basket}/{tenantId}/{fileName}
+```
+
+**Примеры:**
+- `s3://uploads/42/document.pdf`
+- `s3://media/7/video.mp4`
+- `s3://share/100/data.bin`
+
+---
+
+## Установка
+
+```powershell
+dotnet add package Sa.HybridFileStorage.S3
+```
+
+---
+
+## Быстрый старт
+
+### Без DI
+
+```csharp
+using Sa.HybridFileStorage.S3;
+using Sa.HybridFileStorage.Domain;
+
+var options = new S3FileStorageOptions
+{
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ Bucket = "mybucket",
+ Basket = "uploads"
+};
+
+// Требуется предварительно зарегистрированный IS3BucketClient
+var client = new S3BucketClient(new S3BucketClientSetupSettings
+{
+ Endpoint = options.Endpoint,
+ AccessKey = options.AccessKey,
+ SecretKey = options.SecretKey,
+ Region = options.Region,
+ Bucket = options.Bucket
+});
+
+using var storage = new S3FileStorage(client, options);
+
+// Загрузка
+using var stream = File.OpenRead(@"C:\temp\document.pdf");
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "document.pdf", TenantId = 42 },
+ stream, ct);
+
+Console.WriteLine(result.FileId); // s3://uploads/42/document.pdf
+Console.WriteLine(result.AbsoluteUrl); // http://localhost:9000/mybucket/uploads/42/document.pdf
+```
+
+### С DI
+
+```csharp
+using Sa.HybridFileStorage.S3;
+
+builder.Services.AddSaS3FileStorage(new S3FileStorageOptions
+{
+ Endpoint = "http://localhost:9000",
+ AccessKey = "ROOTUSER",
+ SecretKey = "ChangeMe123",
+ Bucket = "mybucket",
+ Basket = "uploads"
+});
+
+// AddSaS3FileStorage автоматически регистрирует IS3BucketClient через AddSaS3BucketClient
+```
+
+---
+
+## Примеры CRUD
+
+### Загрузка из Stream
+
+```csharp
+using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, S3!"));
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "hello.txt", TenantId = 1 },
+ stream, ct);
+
+// Файл сохранён: mybucket/uploads/1/hello.txt
+// Content-Type: text/plain (автоопределён из расширения)
+```
+
+### Загрузка больших файлов
+
+```csharp
+// Потоковая загрузка без загрузки в память
+await using var fs = new FileStream(@"C:\large\data.zip", new FileStreamOptions
+{
+ Mode = FileMode.Open,
+ Access = FileAccess.Read,
+ Share = FileShare.Read,
+ Options = FileOptions.Asynchronous | FileOptions.SequentialScan
+});
+
+var result = await storage.UploadAsync(
+ new UploadFileInput { FileName = "data.zip", TenantId = 5 },
+ fs, ct);
+```
+
+### Скачивание в память
+
+```csharp
+byte[]? downloaded = default;
+await storage.DownloadAsync(result.FileId, async (stream, token) =>
+{
+ downloaded = await stream.ReadAllBytesAsync(token);
+}, ct);
+```
+
+### Скачивание на диск
+
+```csharp
+await using var destination = new FileStream(@"C:\output\downloaded.pdf", FileMode.Create);
+await storage.DownloadAsync(result.FileId, async (source, token) =>
+ await source.CopyToAsync(destination, 1024 * 1024, token), // 1 MB буфер
+ ct);
+```
+
+### Получение метаданных
+
+```csharp
+var metadata = await storage.GetMetadataAsync(result.FileId, ct);
+if (metadata != null)
+{
+ Console.WriteLine($"Корзина: {metadata.Basket}"); // uploads
+ Console.WriteLine($"Тенант: {metadata.TenantId}"); // 42
+ Console.WriteLine($"Имя: {metadata.FileName}"); // document.pdf
+ Console.WriteLine($"Тип: {metadata.StorageType}"); // s3
+}
+```
+
+### Удаление
+
+```csharp
+bool deleted = await storage.DeleteAsync(result.FileId, ct);
+// Всегда возвращает true, если CanProcess(fileId) == true — S3 игнорирует отсутствие объектов
+```
+
+---
+
+## Справочник настроек
+
+### S3FileStorageOptions
+
+| Свойство | Описание | По умолчанию |
+|----------|----------|-------------|
+| `Endpoint` | URL S3-совместимого эндпоинта | *(обязательно)* |
+| `AccessKey` | Ключ доступа | *(обязательно)* |
+| `SecretKey` | Секретный ключ | *(обязательно)* |
+| `Bucket` | Имя целевого бакета | *(обязательно)* |
+| `Basket` | Префикс области/контейнера внутри бакета | `"share"` |
+| `Region` | Регион AWS для SigV4 подписи | `"eu-central-1"` |
+| `StorageType` | Префикс схемы в File ID | `"s3"` |
+| `IsReadOnly` | Запрет операций записи/удаления | `false` |
+
+---
+
+## Зависимости
+
+| Пакет | Назначение |
+|-------|-----------|
+| `Sa.Data.S3` | S3 клиент (`IS3BucketClient`, `S3BucketClient`) |
+| `Sa` | Общие утилиты (`MimeTypeMap`) |
+
+Метод расширения `AddSaS3FileStorage` автоматически регистрирует `IS3BucketClient` через `AddSaS3BucketClient`.
+
+---
+
+## Лицензия
+
+MIT
diff --git a/src/Sa.HybridFileStorage.S3/S3FileStorage.cs b/src/Sa.HybridFileStorage.S3/S3FileStorage.cs
index 3c748af9..469eeade 100644
--- a/src/Sa.HybridFileStorage.S3/S3FileStorage.cs
+++ b/src/Sa.HybridFileStorage.S3/S3FileStorage.cs
@@ -1,5 +1,6 @@
using Sa.Classes;
using Sa.Data.S3;
+using Sa.HybridFileStorage;
using Sa.HybridFileStorage.Domain;
using System.Globalization;
using System.Runtime.CompilerServices;
@@ -21,7 +22,9 @@ internal sealed class S3FileStorage(
private readonly string _storageType = options.StorageType;
private readonly bool _isReadOnly = options.IsReadOnly;
private readonly TimeProvider _timeProvider = timeProvider ?? TimeProvider.System;
- private int _bucketEnsured; // 0 = not ensured, 1 = ensured (thread-safe via Interlocked)
+
+ // Async lazy initialization for bucket ensure — prevents concurrent CreateBucket calls
+ private volatile Task _ensureBucketTask;
public string StorageType => _storageType;
public bool IsReadOnly => _isReadOnly;
@@ -44,6 +47,10 @@ public bool CanProcess(string? fileId)
public async Task DeleteAsync(string fileId, CancellationToken cancellationToken)
{
EnsureWritable();
+
+ if (!CanProcess(fileId))
+ return false;
+
var filePath = GetFilePath(fileId);
await client.DeleteFile(filePath, cancellationToken).ConfigureAwait(false);
return true;
@@ -54,6 +61,10 @@ public async Task DownloadAsync(
Func loadStream,
CancellationToken cancellationToken)
{
+
+ if (!CanProcess(fileId))
+ return false;
+
var filePath = GetFilePath(fileId);
using var stream = await client.GetFileStream(filePath, cancellationToken).ConfigureAwait(false);
if (stream is null || stream == Stream.Null) return false;
@@ -68,6 +79,9 @@ public async Task UploadAsync(
CancellationToken cancellationToken)
{
EnsureWritable();
+ ArgumentNullException.ThrowIfNull(fileStream);
+
+ metadata.Validate();
await EnsureBucketAsync(cancellationToken).ConfigureAwait(false);
// Оптимизированная сборка пути без лишних аллокаций
@@ -87,20 +101,41 @@ public async Task UploadAsync(
_timeProvider.GetUtcNow());
}
- private async ValueTask EnsureBucketAsync(CancellationToken cancellationToken)
+ private async Task EnsureBucketAsync(CancellationToken cancellationToken)
+ {
+ // Fast path: if already ensured, skip entirely
+ var task = _ensureBucketTask;
+ if (task is not null)
+ {
+ await task.ConfigureAwait(false);
+ return;
+ }
+
+ // Slow path: create the task that will ensure the bucket
+ var createdTask = EnsureBucketCoreAsync(cancellationToken);
+
+ // CompareExchange ensures only one task survives — others will await the winner
+ var comparison = Interlocked.CompareExchange(ref _ensureBucketTask, createdTask, null);
+ if (comparison is not null)
+ {
+ // Another thread won the race — await its task and discard ours
+ await createdTask.ConfigureAwait(false);
+ await comparison.ConfigureAwait(false);
+ return;
+ }
+
+ // We won — execute and let callers await the result
+ await createdTask.ConfigureAwait(false);
+ }
+
+ private async Task EnsureBucketCoreAsync(CancellationToken cancellationToken)
{
- // Lock-free проверка: проверяем bucket только один раз за время жизни экземпляра
- if (Volatile.Read(ref _bucketEnsured) == 0)
+ if (await client.IsBucketExists(cancellationToken).ConfigureAwait(false))
{
- if (await client.IsBucketExists(cancellationToken).ConfigureAwait(false))
- {
- Volatile.Write(ref _bucketEnsured, 1);
- return;
- }
-
- await client.CreateBucket(cancellationToken).ConfigureAwait(false);
- Volatile.Write(ref _bucketEnsured, 1);
+ return;
}
+
+ await client.CreateBucket(cancellationToken).ConfigureAwait(false);
}
[MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -123,28 +158,14 @@ private static string GetFilePath(string fileId)
{
if (!CanProcess(fileId)) return null;
- var filePath = GetFilePath(fileId);
- ReadOnlySpan pathSpan = filePath.AsSpan();
-
- // Парсинг пути: "scope/tenantId/filename"
- int firstSlash = pathSpan.IndexOf('/');
- if (firstSlash == -1) return null;
-
- var afterScope = pathSpan[(firstSlash + 1)..];
- int secondSlash = afterScope.IndexOf('/');
- if (secondSlash == -1) return null;
-
- var tenantSpan = afterScope[..secondSlash];
- var fileNameSpan = afterScope[(secondSlash + 1)..];
-
- if (!int.TryParse(tenantSpan, NumberStyles.None, CultureInfo.InvariantCulture, out int tenantId))
+ if (!FileIdParser.TryParse(fileId, out var basket, out var tenantId, out _, out var fileName))
return null;
return new FileMetadata
{
- Basket = Basket,
+ Basket = basket,
StorageType = StorageType,
- FileName = fileNameSpan.ToString(),
+ FileName = fileName,
TenantId = tenantId
};
}
diff --git a/src/Sa.HybridFileStorage.S3/S3FileStorageOptions.cs b/src/Sa.HybridFileStorage.S3/S3FileStorageOptions.cs
index cf856220..0cb51a82 100644
--- a/src/Sa.HybridFileStorage.S3/S3FileStorageOptions.cs
+++ b/src/Sa.HybridFileStorage.S3/S3FileStorageOptions.cs
@@ -1,18 +1,47 @@
namespace Sa.HybridFileStorage.S3;
+///
+/// Configuration options for the S3 (MinIO-compatible) file storage provider.
+///
public sealed class S3FileStorageOptions
{
+ ///
+ /// Gets or sets the storage type identifier. Defaults to "s3".
+ ///
public string StorageType { get; init; } = "s3";
+
+ ///
+ /// Gets or sets the basket (container) name. Defaults to "share".
+ ///
public string Basket { get; init; } = "share";
///
- /// http://localhost:9000
+ /// Gets or sets the S3-compatible endpoint URL (e.g., http://localhost:9000).
///
public required string Endpoint { get; init; }
+
+ ///
+ /// Gets or sets the access key for authenticating with the S3 service.
+ ///
public required string AccessKey { get; init; }
+
+ ///
+ /// Gets or sets the secret key for authenticating with the S3 service.
+ ///
public required string SecretKey { get; init; }
+
+ ///
+ /// Gets or sets the name of the S3 bucket to use for file storage.
+ ///
public required string Bucket { get; init; }
+
+ ///
+ /// Gets or sets the AWS region. Defaults to "eu-central-1".
+ ///
public string Region { get; init; } = "eu-central-1";
+ ///
+ /// Gets or sets a value indicating whether this storage is read-only. Defaults to false.
+ ///
public bool IsReadOnly { get; init; } = false;
}
diff --git a/src/Sa.HybridFileStorage.S3/Sa.HybridFileStorage.S3.csproj b/src/Sa.HybridFileStorage.S3/Sa.HybridFileStorage.S3.csproj
index 8923c345..7c7e4314 100644
--- a/src/Sa.HybridFileStorage.S3/Sa.HybridFileStorage.S3.csproj
+++ b/src/Sa.HybridFileStorage.S3/Sa.HybridFileStorage.S3.csproj
@@ -3,7 +3,7 @@
- 0.9.1
+ 0.10.0
File storage management in S3
diff --git a/src/Sa.HybridFileStorage.S3/Setup.cs b/src/Sa.HybridFileStorage.S3/Setup.cs
index 9bdb8123..881cc51e 100644
--- a/src/Sa.HybridFileStorage.S3/Setup.cs
+++ b/src/Sa.HybridFileStorage.S3/Setup.cs
@@ -4,8 +4,17 @@
namespace Sa.HybridFileStorage.S3;
+///
+/// Provides extension methods for registering the S3 file storage provider with the .NET Generic Host.
+///
public static class Setup
{
+ ///
+ /// Registers the S3 file storage provider with the specified service collection.
+ ///
+ /// The service collection to add the services to.
+ /// Configuration options for the S3 storage provider.
+ /// The same instance with the services added.
public static IServiceCollection AddSaS3FileStorage(this IServiceCollection services, S3FileStorageOptions options)
{
var settings = new S3BucketClientSetupSettings
diff --git a/src/Sa.HybridFileStorage/Domain/UploadFileInput.cs b/src/Sa.HybridFileStorage/Domain/UploadFileInput.cs
index 3672b5ed..1fc04a72 100644
--- a/src/Sa.HybridFileStorage/Domain/UploadFileInput.cs
+++ b/src/Sa.HybridFileStorage/Domain/UploadFileInput.cs
@@ -1,9 +1,34 @@
namespace Sa.HybridFileStorage.Domain;
+///
+/// Represents input metadata for a file upload operation.
+///
public sealed record UploadFileInput
{
+ ///
+ /// Gets or sets the tenant identifier associated with the file. Defaults to 0.
+ ///
public int TenantId { get; init; } = 0;
+
+ ///
+ /// Gets or sets the file name. Defaults to an empty string.
+ ///
public string FileName { get; init; } = string.Empty;
+ ///
+ /// Gets a default (empty) instance.
+ ///
public static UploadFileInput Empty { get; } = new();
+
+ ///
+ /// Validates the input metadata. Throws if validation fails.
+ ///
+ public void Validate()
+ {
+ if (string.IsNullOrWhiteSpace(FileName))
+ throw new ArgumentException("File name cannot be null or empty.", nameof(FileName));
+
+ if (TenantId < 0)
+ throw new ArgumentException("TenantId must be greater than or equal to 0.", nameof(TenantId));
+ }
}
diff --git a/src/Sa.HybridFileStorage/Exceptions.cs b/src/Sa.HybridFileStorage/Exceptions.cs
index e335ce37..49ed2530 100644
--- a/src/Sa.HybridFileStorage/Exceptions.cs
+++ b/src/Sa.HybridFileStorage/Exceptions.cs
@@ -1,30 +1,50 @@
-using System.Diagnostics.CodeAnalysis;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
using System.Security;
namespace Sa.HybridFileStorage;
+///
+/// Thrown when no storage provider is available to perform the requested operation.
+///
public class HybridFileStorageNoAvailableException() : Exception("No storage available.");
-
+///
+/// Thrown when an operation fails across multiple storage providers.
+///
public class HybridFileStorageAggregateException(IEnumerable innerExceptions)
: AggregateException("Operation failed for some available storages.", innerExceptions);
-
+///
+/// Thrown when a write operation is attempted but all storage providers are read-only.
+///
public class HybridFileStorageWritableException()
: Exception("Cannot perform operation. All storage options are read-only.");
-
-
+///
+/// Provides static helper methods for throwing hybrid file storage exceptions.
+///
public static class HybridFileStorageThrowHelper
{
+ ///
+ /// Throws a .
+ ///
[DoesNotReturn]
public static void ThrowWritableException() =>
throw new HybridFileStorageWritableException();
+ ///
+ /// Throws a indicating an invalid file ID format.
+ ///
[DoesNotReturn]
public static void ThrowInvalidFileIdFormat() =>
throw new FormatException("Invalid file ID format.");
+ ///
+ /// Throws a indicating that access to the specified path outside the base directory was denied.
+ ///
+ /// The path that caused the security violation.
+ /// The allowed base directory.
[DoesNotReturn]
public static void ThrowSecurityException(string path, string basePath) =>
throw new SecurityException(
diff --git a/src/Sa.HybridFileStorage/FileIdParser.cs b/src/Sa.HybridFileStorage/FileIdParser.cs
new file mode 100644
index 00000000..ed529d53
--- /dev/null
+++ b/src/Sa.HybridFileStorage/FileIdParser.cs
@@ -0,0 +1,104 @@
+using System.Globalization;
+
+namespace Sa.HybridFileStorage;
+
+///
+/// Utility for parsing and constructing file IDs in the format "storageType://basket/tenantId/timestamp/filename".
+///
+public static class FileIdParser
+{
+ ///
+ /// The scheme separator used between storage type and path.
+ ///
+ public const string SchemeSeparator = "://";
+
+ ///
+ /// Tries to parse a file ID into its constituent parts.
+ ///
+ /// The file ID string to parse.
+ /// When this method returns, contains the basket (scope) name, or empty string if parsing failed.
+ /// When this method returns, contains the tenant identifier, or zero if parsing failed.
+ /// When this method returns, contains the Unix timestamp (seconds), or zero if parsing failed.
+ /// When this method returns, contains the file name, or empty string if parsing failed.
+ /// true if the file ID was parsed successfully; otherwise, false.
+ public static bool TryParse(
+ string fileId,
+ out string basket,
+ out int tenantId,
+ out long timestamp,
+ out string fileName)
+ {
+ tenantId = default;
+ timestamp = default;
+ fileName = string.Empty;
+ basket = string.Empty;
+
+ if (string.IsNullOrEmpty(fileId)) return false;
+
+ ReadOnlySpan span = fileId.AsSpan();
+ int schemeEnd = span.IndexOf(SchemeSeparator.AsSpan());
+ if (schemeEnd == -1) return false;
+
+ var afterSpan = span[(schemeEnd + SchemeSeparator.Length)..];
+ int scopeEnd = afterSpan.IndexOf('/');
+ if (scopeEnd == -1) return false;
+
+ basket = afterSpan[..scopeEnd].ToString();
+ afterSpan = afterSpan[(scopeEnd + 1)..];
+
+ // For Postgres: "tenantId/timestamp/filename"
+ // For S3/FileSystem/InMemory: "tenantId/filename" (no timestamp)
+ int firstSlash = afterSpan.IndexOf('/');
+ if (firstSlash == -1) return false;
+
+ var firstPart = afterSpan[..firstSlash];
+ if (!int.TryParse(firstPart, NumberStyles.None, CultureInfo.InvariantCulture, out tenantId))
+ return false;
+
+ var afterFirst = afterSpan[(firstSlash + 1)..];
+
+ // Check if second part is a timestamp (Postgres) or filename (others)
+ int secondSlash = afterFirst.IndexOf('/');
+ if (secondSlash != -1 && long.TryParse(afterFirst[..secondSlash], NumberStyles.None, CultureInfo.InvariantCulture, out timestamp))
+ {
+ // Postgres format: tenantId/timestamp/filename
+ fileName = afterFirst[(secondSlash + 1)..].ToString();
+ }
+ else
+ {
+ // Simple format: tenantId/filename
+ fileName = afterFirst.ToString();
+ }
+
+ return !string.IsNullOrEmpty(fileName);
+ }
+
+ ///
+ /// Formats a file ID using the Postgres-compatible format with timestamp.
+ ///
+ /// The storage type identifier (e.g., "pg").
+ /// The basket (scope) name.
+ /// The tenant identifier.
+ /// The date associated with the file.
+ /// The file name.
+ /// A formatted file ID string.
+ public static string FormatToFileId(
+ string storageType,
+ string basket,
+ int tenantId,
+ DateTimeOffset date,
+ string fileName)
+ => $"{storageType}://{basket}/{tenantId}/{date.ToUnixTimeSeconds()}/{NormalizeFileName(fileName)}";
+
+ ///
+ /// Normalizes a file name by removing leading slashes/backslashes and converting backslashes to forward slashes.
+ ///
+ public static string NormalizeFileName(string fileName)
+ => fileName.TrimStart('\\', '/').Replace('\\', '/');
+
+ ///
+ /// Extracts the file extension from a file name.
+ ///
+ public static string GetFileExtension(string fileName)
+ => Path.GetExtension(fileName ?? string.Empty).ToLower().TrimStart('.');
+}
diff --git a/src/Sa.HybridFileStorage/FileMetadata.cs b/src/Sa.HybridFileStorage/FileMetadata.cs
index 65e3f4d5..12942a3c 100644
--- a/src/Sa.HybridFileStorage/FileMetadata.cs
+++ b/src/Sa.HybridFileStorage/FileMetadata.cs
@@ -1,9 +1,27 @@
namespace Sa.HybridFileStorage;
+///
+/// Represents metadata for a file stored in the hybrid file storage system.
+///
public sealed class FileMetadata
{
+ ///
+ /// Gets or sets the basket (container) name where the file is stored.
+ ///
public required string Basket { get; init; }
+
+ ///
+ /// Gets or sets the file name.
+ ///
public required string FileName { get; init; }
+
+ ///
+ /// Gets or sets the tenant identifier associated with the file.
+ ///
public int TenantId { get; init; }
+
+ ///
+ /// Gets the storage type identifier (e.g., "fs", "s3", "pg").
+ ///
public required string StorageType { get; init; }
}
diff --git a/src/Sa.HybridFileStorage/HybridFileStorage.cs b/src/Sa.HybridFileStorage/HybridFileStorage.cs
index 2449a82b..af352b64 100644
--- a/src/Sa.HybridFileStorage/HybridFileStorage.cs
+++ b/src/Sa.HybridFileStorage/HybridFileStorage.cs
@@ -13,13 +13,27 @@ internal sealed class HybridFileStorage(
private void EnsureWritable(string basket)
{
- if (!container.Storages.Any(c => c.Basket == basket))
+ bool hasWritable = false;
+ bool hasAny = false;
+
+ foreach (var storage in container.Storages)
{
- throw new HybridFileStorageNoAvailableException();
+ if (storage.Basket == basket)
+ {
+ hasAny = true;
+ if (!storage.IsReadOnly)
+ {
+ hasWritable = true;
+ }
+ }
}
+ if (!hasAny)
+ {
+ throw new HybridFileStorageNoAvailableException();
+ }
- if (Storages.All(f => f.Basket == basket && f.IsReadOnly))
+ if (!hasWritable)
{
throw new HybridFileStorageWritableException();
}
@@ -38,12 +52,12 @@ public async Task UploadAsync(
return await ExecuteStorageOperationAsync(
container.Storages.Where(c => !c.IsReadOnly && c.Basket == basket),
- async (storage, ct) => await interceptors.ExecuteBeforeUploadAsync(storage, input, fileStream, ct),
- async (storage, ct) => await storage.UploadAsync(input, fileStream, ct),
- interceptors.ExecuteAfterUploadAsync,
- interceptors.ExecuteOnUploadErrorAsync,
+ async (storage, ct) => await interceptors.ExecuteBeforeUploadAsync(storage, input, fileStream, ct).ConfigureAwait(false),
+ async (storage, ct) => await storage.UploadAsync(input, fileStream, ct).ConfigureAwait(false),
+ async (storage, result, ct) => await interceptors.ExecuteAfterUploadAsync(storage, result, ct).ConfigureAwait(false),
+ async (storage, e, ct) => await interceptors.ExecuteOnUploadErrorAsync(storage, e, ct).ConfigureAwait(false),
cancellationToken
- );
+ ).ConfigureAwait(false);
}
public async Task DownloadAsync(
@@ -55,12 +69,12 @@ public async Task DownloadAsync(
return await ExecuteStorageOperationAsync(
CanProcess(fileId),
- async (storage, ct) => await interceptors.ExecuteBeforeDownloadAsync(storage, fileId, loadStream, ct),
- async (storage, ct) => await storage.DownloadAsync(fileId, loadStream, ct),
- async (storage, result, ct) => await interceptors.ExecuteAfterDownloadAsync(storage, fileId, result, ct),
- async (storage, e, ct) => await interceptors.ExecuteOnDownloadErrorAsync(storage, fileId, e, ct),
+ async (storage, ct) => await interceptors.ExecuteBeforeDownloadAsync(storage, fileId, loadStream, ct).ConfigureAwait(false),
+ async (storage, ct) => await storage.DownloadAsync(fileId, loadStream, ct).ConfigureAwait(false),
+ async (storage, result, ct) => await interceptors.ExecuteAfterDownloadAsync(storage, fileId, result, ct).ConfigureAwait(false),
+ async (storage, e, ct) => await interceptors.ExecuteOnDownloadErrorAsync(storage, fileId, e, ct).ConfigureAwait(false),
cancellationToken
- );
+ ).ConfigureAwait(false);
}
public async Task DeleteAsync(
@@ -71,12 +85,12 @@ public async Task DeleteAsync(
return await ExecuteStorageOperationAsync(
CanProcess(fileId).Where(c => !c.IsReadOnly),
- async (storage, ct) => await interceptors.ExecuteBeforeDeleteAsync(storage, fileId, ct),
- async (storage, ct) => await storage.DeleteAsync(fileId, ct),
- async (storage, result, ct) => await interceptors.ExecuteAfterDeleteAsync(storage, fileId, result, ct),
- async (storage, e, ct) => await interceptors.ExecuteOnDeleteErrorAsync(storage, fileId, e, ct),
+ async (storage, ct) => await interceptors.ExecuteBeforeDeleteAsync(storage, fileId, ct).ConfigureAwait(false),
+ async (storage, ct) => await storage.DeleteAsync(fileId, ct).ConfigureAwait(false),
+ async (storage, result, ct) => await interceptors.ExecuteAfterDeleteAsync(storage, fileId, result, ct).ConfigureAwait(false),
+ async (storage, e, ct) => await interceptors.ExecuteOnDeleteErrorAsync(storage, fileId, e, ct).ConfigureAwait(false),
cancellationToken
- );
+ ).ConfigureAwait(false);
}
@@ -94,15 +108,15 @@ private static async Task ExecuteStorageOperationAsync(
{
try
{
- if (!await beforeOperation(storage, cancellationToken)) continue;
- var result = await operation(storage, cancellationToken);
- await afterOperation(storage, result, cancellationToken);
+ if (!await beforeOperation(storage, cancellationToken).ConfigureAwait(false)) continue;
+ var result = await operation(storage, cancellationToken).ConfigureAwait(false);
+ await afterOperation(storage, result, cancellationToken).ConfigureAwait(false);
return result;
}
catch (Exception e)
{
exceptions.Add(e);
- await onError(storage, e, cancellationToken);
+ await onError(storage, e, cancellationToken).ConfigureAwait(false);
}
}
@@ -122,7 +136,7 @@ private static async Task ExecuteStorageOperationAsync(
foreach (var fs in container.Storages)
{
- var meta = await fs.GetMetadataAsync(fileId, cancellationToken);
+ var meta = await fs.GetMetadataAsync(fileId, cancellationToken).ConfigureAwait(false);
if (meta != null) return meta;
}
diff --git a/src/Sa.HybridFileStorage/HybridFileStorageContainer.cs b/src/Sa.HybridFileStorage/HybridFileStorageContainer.cs
index 2a75ebe9..96b0b0fb 100644
--- a/src/Sa.HybridFileStorage/HybridFileStorageContainer.cs
+++ b/src/Sa.HybridFileStorage/HybridFileStorageContainer.cs
@@ -2,18 +2,49 @@
namespace Sa.HybridFileStorage;
+///
+/// Thread-safe container for multiple providers.
+/// Uses copy-on-write semantics to allow safe enumeration during concurrent mutations.
+///
internal sealed class HybridFileStorageContainer(IEnumerable storages) : IHybridFileStorageContainer
{
+ private readonly ReaderWriterLockSlim _lock = new(LockRecursionPolicy.NoRecursion);
private readonly List _storages = [.. storages];
- public IHybridFileStorageContainerConfiguration AddStorage(IFileStorage storage)
+ ///
+ public HybridFileStorageContainerConfiguration AddStorage(IFileStorage storage)
{
- if (!_storages.Contains(storage))
+ _lock.EnterWriteLock();
+ try
{
- _storages.Add(storage);
+ if (!_storages.Contains(storage))
+ {
+ _storages.Add(storage);
+ }
}
- return this;
+ finally
+ {
+ _lock.ExitWriteLock();
+ }
+
+ return new HybridFileStorageContainerConfiguration(AddStorage);
}
- public IEnumerable Storages => _storages;
+ ///
+ public IEnumerable Storages
+ {
+ get
+ {
+ _lock.EnterReadLock();
+ try
+ {
+ // Snapshot to avoid holding the lock during enumeration
+ return [.. _storages];
+ }
+ finally
+ {
+ _lock.ExitReadLock();
+ }
+ }
+ }
}
diff --git a/src/Sa.HybridFileStorage/HybridFileStorageContainerConfiguration.cs b/src/Sa.HybridFileStorage/HybridFileStorageContainerConfiguration.cs
new file mode 100644
index 00000000..06a862ad
--- /dev/null
+++ b/src/Sa.HybridFileStorage/HybridFileStorageContainerConfiguration.cs
@@ -0,0 +1,26 @@
+using Sa.HybridFileStorage.Domain;
+
+namespace Sa.HybridFileStorage;
+
+///
+/// Fluent builder for registering file storage providers into the hybrid container.
+///
+public sealed class HybridFileStorageContainerConfiguration
+{
+ private readonly Func _addStorage;
+
+ internal HybridFileStorageContainerConfiguration(Func addStorage)
+ {
+ _addStorage = addStorage ?? throw new ArgumentNullException(nameof(addStorage));
+ }
+
+ ///
+ /// Adds a file storage provider to the hybrid file storage container.
+ ///
+ /// The storage implementation to register.
+ /// The same instance for chaining.
+ public HybridFileStorageContainerConfiguration AddStorage(IFileStorage storage)
+ {
+ return _addStorage(storage);
+ }
+}
diff --git a/src/Sa.HybridFileStorage/HybridFileStorageExtensions.cs b/src/Sa.HybridFileStorage/HybridFileStorageExtensions.cs
index e4d782be..35c0b8dd 100644
--- a/src/Sa.HybridFileStorage/HybridFileStorageExtensions.cs
+++ b/src/Sa.HybridFileStorage/HybridFileStorageExtensions.cs
@@ -3,8 +3,21 @@
namespace Sa.HybridFileStorage;
+///
+/// Provides extension methods for common file storage operations on .
+///
public static class HybridFileStorageExtensions
{
+ ///
+ /// Copies a file from the local filesystem into the hybrid file storage.
+ ///
+ /// The hybrid file storage instance.
+ /// The path to the local file to upload.
+ /// The target basket (container) name.
+ /// Metadata about the file being uploaded.
+ /// The size of the buffer used when reading the file. Defaults to 81920 bytes.
+ /// A cancellation token to cancel the operation if needed.
+ /// A containing the result of the upload operation.
public static async Task CopyFromFileAsync(
this IHybridFileStorage storage,
string filePath,
@@ -13,7 +26,11 @@ public static async Task CopyFromFileAsync(
int bufferSize = 81920,
CancellationToken ct = default)
{
- // копируем файл в хранилище
+ ArgumentNullException.ThrowIfNull(storage);
+ ArgumentNullException.ThrowIfNull(filePath);
+ ArgumentNullException.ThrowIfNull(basket);
+ ArgumentNullException.ThrowIfNull(input);
+
await using var fs = new FileStream(filePath, new FileStreamOptions
{
Mode = FileMode.Open,
@@ -27,9 +44,21 @@ public static async Task CopyFromFileAsync(
basket: basket,
input: input,
fileStream: fs,
- cancellationToken: ct);
+ cancellationToken: ct)
+ .ConfigureAwait(false);
}
+ ///
+ /// Copies a file from one storage scope (basket) to another within the hybrid file storage system.
+ ///
+ /// The hybrid file storage instance.
+ /// The unique identifier of the source file.
+ /// The target basket (container) name.
+ /// An optional callback to customize the upload metadata based on the source file's metadata.
+ /// A cancellation token to cancel the operation if needed.
+ /// A containing the result of the upload operation in the target basket.
+ /// Thrown when the source file does not exist.
+ /// Thrown when the file is already in the target scope.
public static async Task CopyToBasketAsync(
this IHybridFileStorage storage,
string fileId,
@@ -37,7 +66,12 @@ public static async Task CopyToBasketAsync(
Func? configure = null,
CancellationToken ct = default)
{
- var metadata = await storage.GetMetadataAsync(fileId, ct);
+ ArgumentNullException.ThrowIfNull(storage);
+ ArgumentNullException.ThrowIfNull(fileId);
+ ArgumentNullException.ThrowIfNull(basket);
+
+ var metadata = await storage.GetMetadataAsync(fileId, ct)
+ .ConfigureAwait(false);
if (metadata is null)
{
@@ -66,9 +100,11 @@ public static async Task CopyToBasketAsync(
basket,
uploadInput,
sourceStream,
- downloadCt);
+ downloadCt)
+ .ConfigureAwait(false);
},
- ct);
+ ct)
+ .ConfigureAwait(false);
if (!downloaded)
{
@@ -78,16 +114,16 @@ public static async Task CopyToBasketAsync(
return result;
}
-
- [DoesNotReturn]
- static void ThrowFileAlreadyInTargetScope() =>
- throw new InvalidOperationException("File already in target scope");
-
- [DoesNotReturn]
- static void ThrowSourceFileNotFound(string fileId) =>
- throw new FileNotFoundException($"Source file not found: {fileId}");
-
-
+ ///
+ /// Copies multiple files from various storage scopes to a target basket in parallel.
+ ///
+ /// The hybrid file storage instance.
+ /// The collection of file IDs to copy.
+ /// The target basket (container) name.
+ /// An optional callback to customize the upload metadata based on each source file's metadata.
+ /// Optional settings controlling parallelism, timeout, error handling, and progress reporting.
+ /// A cancellation token to cancel the entire batch operation.
+ /// A containing lists of succeeded results and failed errors.
public static async Task> CopyToScopeBatchAsync(
this IHybridFileStorage storage,
IEnumerable fileIds,
@@ -96,6 +132,9 @@ public static async Task> CopyToScopeBatchAsync(
BatchOptions? options = default,
CancellationToken cancellationToken = default)
{
+ ArgumentNullException.ThrowIfNull(storage);
+ ArgumentNullException.ThrowIfNull(fileIds);
+ ArgumentNullException.ThrowIfNull(basket);
var opts = options ?? new BatchOptions();
var fileList = fileIds as IList ?? [.. fileIds];
@@ -114,75 +153,102 @@ public static async Task> CopyToScopeBatchAsync(
var progress = opts.Progress;
int completed = 0;
+ // Объект для синхронизации доступа к общим коллекциям и счетчикам
+ Lock lockObj = new ();
- async Task ProcessFileAsync(string fileId, int index)
+ async Task ProcessFileAsync(string fileId, int index, CancellationToken ct)
{
try
{
+ // Используем ct от делегата, а не внешний cancellationToken
using var cts = opts.OperationTimeout > TimeSpan.Zero
- ? CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)
+ ? CancellationTokenSource.CreateLinkedTokenSource(ct)
: null;
cts?.CancelAfter(opts.OperationTimeout);
- var ct = cts?.Token ?? cancellationToken;
+ var operationCt = cts?.Token ?? ct;
return await storage.CopyToBasketAsync(
fileId,
basket,
configure,
- ct: ct);
+ ct: operationCt)
+ .ConfigureAwait(false);
}
catch (Exception ex)
{
- failed.Add(new BatchError(fileId, ex, index));
+ // Lock only for adding to failed list and incrementing counter
+ int failedIdx;
+ int completedCount;
+ lock (lockObj)
+ {
+ failed.Add(new BatchError(fileId, ex, index));
+ completed++;
+ failedIdx = failed.Count - 1;
+ completedCount = completed;
+ }
+
+ // Progress.Report outside lock to avoid blocking other threads during user callback
+ var reportedError = failed[failedIdx];
progress?.Report(new BatchOperationProgress(
fileList.Count,
- Interlocked.Increment(ref completed),
+ completedCount,
succeeded.Count,
failed.Count,
- fileId,
- ex));
+ reportedError.FileId,
+ reportedError.Exception));
+
return null;
}
}
-
var parallelOptions = new ParallelOptions
{
CancellationToken = cancellationToken,
MaxDegreeOfParallelism = opts.MaxDegreeOfParallelism
};
- await Parallel.ForEachAsync(fileList.Select((id, idx) => (id, idx)), parallelOptions, async (item, ct) =>
- {
- var (fileId, index) = item;
-
- if (!opts.ContinueOnError && failed.Count > 0)
+ await Parallel.ForEachAsync(
+ fileList.Select((id, idx) => (id, idx)),
+ parallelOptions,
+ async (item, ct) =>
{
- return;
- }
+ var (fileId, index) = item;
- var result = await ProcessFileAsync(fileId, index);
+ bool hasFailed;
+ lock (lockObj)
+ {
+ hasFailed = failed.Count > 0;
+ }
- if (result is not null)
- {
- lock (succeeded)
+ if (!opts.ContinueOnError && hasFailed)
{
- succeeded.Add(result);
+ return;
}
- }
- if (result is not null)
- {
- progress?.Report(new BatchOperationProgress(
- fileList.Count,
- Interlocked.Increment(ref completed),
- succeeded.Count,
- failed.Count,
- fileId));
- }
- });
+ var result = await ProcessFileAsync(fileId, index, ct)
+ .ConfigureAwait(false);
+
+ if (result is not null)
+ {
+ BatchOperationProgress progressSnapshot;
+ lock (lockObj)
+ {
+ succeeded.Add(result);
+ completed++;
+ progressSnapshot = new BatchOperationProgress(
+ fileList.Count,
+ completed,
+ succeeded.Count,
+ failed.Count,
+ fileId);
+ }
+
+ // Report outside lock to avoid blocking other threads during user callback
+ progress?.Report(progressSnapshot);
+ }
+ });
return new BatchResult
{
@@ -190,4 +256,12 @@ await Parallel.ForEachAsync(fileList.Select((id, idx) => (id, idx)), parallelOpt
Failed = failed.AsReadOnly()
};
}
+
+ [DoesNotReturn]
+ static void ThrowFileAlreadyInTargetScope() =>
+ throw new InvalidOperationException("File already in target scope");
+
+ [DoesNotReturn]
+ static void ThrowSourceFileNotFound(string fileId) =>
+ throw new FileNotFoundException($"Source file not found: {fileId}");
}
diff --git a/src/Sa.HybridFileStorage/HybridStorageBuilder.cs b/src/Sa.HybridFileStorage/HybridStorageBuilder.cs
index e7b80fcd..cd1fe9bb 100644
--- a/src/Sa.HybridFileStorage/HybridStorageBuilder.cs
+++ b/src/Sa.HybridFileStorage/HybridStorageBuilder.cs
@@ -7,12 +7,12 @@ namespace Sa.HybridFileStorage;
internal sealed class HybridStorageBuilder(IServiceCollection services) : IHybridFileStorageConfiguration
{
- private Action? _configureStorage;
+ private Action? _configureStorage;
private Action? _configureInterceptors;
private bool _logged = false;
public IHybridFileStorageConfiguration ConfigureStorage(
- Action configure)
+ Action configure)
{
_configureStorage = configure;
return this;
@@ -35,19 +35,25 @@ public void Build()
{
if (_logged)
{
- services.TryAddSingleton