Українська
Файли й реєстрація
Крок 1. Зберігайте файли на диску
Навіщо. Вкладення й аватари – це файли, а файлам у базі даних не місце: вони зробили б резервні копії величезними, а кожне читання повільним. Chatex тримає їх у папці на диску – /var/lib/chatex/uploads на сервері, .uploads у репозиторії під час розробки – а база даних зберігає лише їхній шлях у сховищі.
Небезпека файлів – обхід шляхів (path traversal). Якби шлях у сховищі колись містив ../../etc/passwd, Path.Combine(root, path) указував би за межі папки завантажень. Chatex зачиняє ці двері двічі:
- сама служба сховища вибирає кожен шлях із дати й нового UUID (
2026/11/0199f3c2…), тож імена файлів клієнта ніколи не стають шляхами; - кожен шлях перетворюється на повний і все одно має починатися з кореневої папки; інакше виклик завершується помилкою.
Що зробити. Створіть папку Storage із класом налаштувань і сховищем:
cs
namespace Chatex.Data.Storage;
public sealed class FileStorageOptions
{
/// <summary>Directory that holds all uploads, outside the web root (production: <c>/var/lib/chatex/uploads</c>).</summary>
public string RootPath { get; set; } = "";
}cs
using Chatex.Data.Abstractions;
using Microsoft.Extensions.Options;
namespace Chatex.Data.Storage;
/// <summary>Keeps files on the local disk under <see cref="FileStorageOptions.RootPath"/>/yyyy/MM/{guid}.</summary>
internal sealed class LocalFileStorage(IOptions<FileStorageOptions> options, TimeProvider timeProvider) : IFileStorage
{
private readonly string _root = Path.GetFullPath(options.Value.RootPath);
public async Task<string> SaveAsync(Stream content, CancellationToken cancellationToken = default)
{
var now = timeProvider.GetUtcNow();
var storagePath = $"{now:yyyy}/{now:MM}/{Guid.CreateVersion7():N}";
var fullPath = ToFullPath(storagePath);
Directory.CreateDirectory(Path.GetDirectoryName(fullPath)!);
try
{
await using var file = new FileStream(fullPath, FileMode.CreateNew, FileAccess.Write, FileShare.None, 81920, useAsync: true);
await content.CopyToAsync(file, cancellationToken);
}
catch
{
File.Delete(fullPath);
throw;
}
return storagePath;
}
public Task<Stream> OpenReadAsync(string storagePath, CancellationToken cancellationToken = default)
{
Stream stream = new FileStream(ToFullPath(storagePath), FileMode.Open, FileAccess.Read, FileShare.Read, 81920, useAsync: true);
return Task.FromResult(stream);
}
public Task DeleteAsync(string storagePath, CancellationToken cancellationToken = default)
{
File.Delete(ToFullPath(storagePath));
return Task.CompletedTask;
}
private string ToFullPath(string storagePath)
{
var fullPath = Path.GetFullPath(Path.Combine(_root, storagePath));
if (!fullPath.StartsWith(_root + Path.DirectorySeparatorChar, StringComparison.Ordinal))
{
throw new ArgumentException($"Storage path '{storagePath}' points outside the storage root.", nameof(storagePath));
}
return fullPath;
}
}IOptions<FileStorageOptions>– це шаблон параметрів (options pattern) .NET: налаштування – це клас, який заповнюють із конфігурації й упроваджують._rootобчислюється один раз, як повний шлях.FileMode.CreateNewзавершується помилкою, якщо файл уже існує – зі свіжим UUID цього ніколи не буває, але якби й сталося, нічого не було б перезаписано.useAsync: trueвідкриває файл для асинхронного введення-виведення, тож повільний диск не блокує потік вебсервера; 81920 байтів – розмір буфера, якийCopyToAsyncвикористовує за замовчуванням.- Невдале завантаження не лишає напівзаписаного файлу:
catchвидаляє його й повторно викидає виняток. ToFullPath– це захист від обходу.Path.GetFullPathрозв’язує сегменти..; перевіркаStartsWith(_root + separator, StringComparison.Ordinal)порівнює символ за символом, без правил культури.
Крок 2. Перевірка стану
Навіщо. На сервері розгортання з теми 24 запускає нову версію й питає в GET /health, чи вона працює; якщо ні, відкочується. «Працює» означає насамперед, що база даних досяжна. В ASP.NET Core є каркас перевірок стану (health checks); рівень даних додає перевірку бази даних.
Що зробити. Додайте пакет:
powershell
dotnet add Source/Chatex.Data package Microsoft.Extensions.Diagnostics.HealthChecksxml
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<PackageReference Include="EFCore.NamingConventions" />
<PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" />
<PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design">
<!-- ... -->
</PackageReference>
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" />
</ItemGroup>
</Project>cs
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Diagnostics.HealthChecks;
namespace Chatex.Data;
/// <summary>
/// Runs <c>SELECT 1</c> on a plain connection. It deliberately bypasses the EF execution strategy: retrying a dead
/// database for half a minute would only delay the 503 that tells the deploy to roll back.
/// </summary>
internal sealed class DatabaseHealthCheck(ChatexDbContext db) : IHealthCheck
{
public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
{
try
{
var connection = db.Database.GetDbConnection();
await connection.OpenAsync(cancellationToken);
try
{
await using var command = connection.CreateCommand();
command.CommandText = "SELECT 1";
await command.ExecuteScalarAsync(cancellationToken);
}
finally
{
await connection.CloseAsync();
}
return HealthCheckResult.Healthy();
}
catch (Exception ex) when (ex is not OperationCanceledException || !cancellationToken.IsCancellationRequested)
{
return HealthCheckResult.Unhealthy("The database cannot be reached.", ex);
}
}
}Перевірка виконує SELECT 1 на звичайному з’єднанні, повз політику повторних спроб EF Core, як пояснює коментар: перевірка стану має відповідати швидко й чесно, а не ховати мертву базу даних за 30 секундами повторів. Фільтр винятків when (ex is not OperationCanceledException || !cancellationToken.IsCancellationRequested) вважає кожен збій «нездоровим», окрім скасування, яке попросив сам викликач.
Крок 3. Зареєструйте рівень даних
Навіщо. Кожен клас рівня даних отримує залежності через конструктор; жоден не створює іншого. Хтось має зібрати граф – це робота контейнера впровадження залежностей .NET. Кожен рівень Chatex реєструє власні сервіси в одному методі розширення, тож застосунок викликає лише AddData, а пізніше AddCore і AddApi.
Час життя кожного сервісу має значення:
| Час життя | Сервіси | Чому |
|---|---|---|
| singleton – один на весь застосунок | TimeProvider, TimestampInterceptor, IFileStorage | вони не зберігають стану окремого запиту |
| scoped – один на область (HTTP-запит, виклик SignalR, крок тесту) | ChatexDbContext, кожен репозиторій, IUnitOfWork | вони мають спільно використовувати один контекст, щоб один SaveChangesAsync зафіксував зміни всіх репозиторіїв запиту |
Що зробити. Доповніть DependencyInjection.cs з теми 4 методом AddData (нові рядки виділено зеленим):
cs
using Chatex.Data.Abstractions;
using Chatex.Data.Entities;
using Chatex.Data.Interceptors;
using Chatex.Data.Repositories;
using Chatex.Data.Storage;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
namespace Chatex.Data;
public static class DependencyInjection
{
/// <summary>
/// Registers the DbContext, repositories, unit of work and the Identity stores for <see cref="User"/>.
/// Identity options (password rules, lockout) and token providers are configured by the caller.
/// </summary>
public static IServiceCollection AddData(
this IServiceCollection services, string connectionString, Action<FileStorageOptions> configureStorage)
{
services.TryAddSingleton(TimeProvider.System);
services.AddSingleton<TimestampInterceptor>();
services.AddOptions<FileStorageOptions>()
.Configure(configureStorage)
.Validate(o => !string.IsNullOrWhiteSpace(o.RootPath), "Storage root path is not configured.")
.ValidateOnStart();
services.AddSingleton<IFileStorage, LocalFileStorage>();
services.AddDbContext<ChatexDbContext>((sp, options) =>
{
Configure(options, connectionString);
options.AddInterceptors(sp.GetRequiredService<TimestampInterceptor>());
});
services.AddIdentityCore<User>()
.AddRoles<IdentityRole<Guid>>()
.AddEntityFrameworkStores<ChatexDbContext>();
services.AddScoped<IUnitOfWork, UnitOfWork>();
services.AddScoped<IUserRepository, UserRepository>();
services.AddScoped<IRefreshTokenRepository, RefreshTokenRepository>();
services.AddScoped<IChatRepository, ChatRepository>();
services.AddScoped<IChatMemberRepository, ChatMemberRepository>();
services.AddScoped<IMessageRepository, MessageRepository>();
services.AddScoped<IAttachmentRepository, AttachmentRepository>();
// Readiness: /health answers 503 while the database cannot be reached.
services.AddHealthChecks().AddCheck<DatabaseHealthCheck>("database", timeout: TimeSpan.FromSeconds(5));
return services;
}
/// <summary>
/// Transient failures (a dropped connection, a failover) are retried. Explicit transactions must go through
/// <see cref="IUnitOfWork.ExecuteInTransactionAsync{T}"/>, which replays the whole unit of work on a retry.
/// </summary>
internal static void Configure(DbContextOptionsBuilder options, string connectionString) =>
options.UseNpgsql(connectionString, npgsql => npgsql.EnableRetryOnFailure()).UseSnakeCaseNamingConvention();
}TryAddSingleton(TimeProvider.System)реєструє справжній годинник, лише якщоTimeProviderще не зареєстровано. Тест, що першим реєструєFakeTimeProvider, зберігає свій підроблений годинник.AddOptions<FileStorageOptions>()…ValidateOnStart()– налаштування сховища перевіряються під час запуску застосунку. Відсутня папка завантажень зупиняє запуск зі зрозумілим повідомленням, а не під час першого завантаження за кілька годин.AddDbContextреєструє контекст як scoped. Його налаштування використовують спільнийConfigureз теми 4 і додають перехоплювач, узятий із контейнера:(sp, options) => …отримує постачальника службsp.AddIdentityCore<User>()реєструєUserManager<User>з Identity та хешер паролів, аAddEntityFrameworkStores<ChatexDbContext>()каже Identity зберігати користувачів у нашому контексті. Тож Identity ділить із запитом його контекст і транзакції, що й уможливлює реєстрацію в одній транзакції (тема 8). Параметри Identity – правила паролів, блокування – належать бізнес-рівню й задаються вAddCore(тема 7).AddHealthChecks().AddCheck<DatabaseHealthCheck>(...)додає перевірку із 5-секундним тайм-аутом; кінцеву точку/healthзіставляють у темі 13.- Коментар до
Configureтепер посилається наIUnitOfWork.ExecuteInTransactionAsync, аusing Chatex.Data.Abstractionsробить це посилання розв’язуваним.
Перевірка
dotnet build успішний, і проєкт даних тепер збігається з еталоном, окрім порядку рядків PackageReference:
powershell
git diff --no-index Source/Chatex.Data D:\Work\Chatex-Reference\Source\Chatex.DataІгноруйте папки bin і obj та імена файлів міграції.
Крок 4. Випробуйте рівень даних
Навіщо. Рівень даних завершено, але ним ще ніхто не користується. Як і в темі 3, невелика програма поза репозиторієм показує його в дії – цього разу на справжній базі даних, через той самий AddData, який викликатиме API.
Що зробити. У вашій папці «пісочниці» (D:\Work\Playground) створіть data.cs. Виправте шлях у першому рядку, якщо ваш репозиторій лежить деінде.
cs
#:project D:\Work\Chatex\Source\Chatex.Data\Chatex.Data.csproj
#:property PublishAot=false
using Chatex.Data;
using Chatex.Data.Abstractions;
using Chatex.Data.Entities;
using Microsoft.AspNetCore.Identity;
using Microsoft.Extensions.DependencyInjection;
var services = new ServiceCollection();
services.AddLogging();
services.AddData(
"Host=localhost;Port=5432;Database=chatex;Username=postgres;Password=postgres",
o => o.RootPath = Path.Combine(Path.GetTempPath(), "chatex-playground"));
await using var provider = services.BuildServiceProvider();
// One scope = one unit of work, like one HTTP request.
await using (var scope = provider.CreateAsyncScope())
{
var users = scope.ServiceProvider.GetRequiredService<UserManager<User>>();
var alice = new User { UserName = "alice", Email = "[email protected]" };
var bob = new User { UserName = "bob", Email = "[email protected]" };
Console.WriteLine($"Create alice: {(await users.CreateAsync(alice, "Passw0rd!")).Succeeded}");
Console.WriteLine($"Create bob: {(await users.CreateAsync(bob, "Passw0rd!")).Succeeded}");
var chat = new Chat
{
Type = ChatType.Direct,
DirectKey = Chat.MakeDirectKey(alice.Id, bob.Id),
CreatedById = alice.Id,
};
chat.Members.Add(new ChatMember { UserId = alice.Id, Role = ChatMemberRole.Member });
chat.Members.Add(new ChatMember { UserId = bob.Id, Role = ChatMemberRole.Member });
scope.ServiceProvider.GetRequiredService<IChatRepository>().Add(chat);
var messages = scope.ServiceProvider.GetRequiredService<IMessageRepository>();
for (var i = 1; i <= 5; i++)
{
messages.Add(new Message { ChatId = chat.Id, SenderId = i % 2 == 0 ? alice.Id : bob.Id, Body = $"Message {i}" });
await Task.Delay(2); // a new millisecond, so the ids are in order
}
var saved = await scope.ServiceProvider.GetRequiredService<IUnitOfWork>().SaveChangesAsync();
Console.WriteLine($"Saved {saved} rows; chat created at {chat.CreatedAt:HH:mm:ss}");
}
await using (var scope = provider.CreateAsyncScope())
{
var alice = await scope.ServiceProvider.GetRequiredService<UserManager<User>>().FindByNameAsync("alice");
var chats = await scope.ServiceProvider.GetRequiredService<IChatRepository>()
.GetUserChatsAsync(alice!.Id, after: null, limit: 20);
foreach (var item in chats.Items)
{
Console.WriteLine($"Chat with {item.Peer?.UserName}: {item.UnreadCount} unread, last: {item.LastMessage?.Body}");
}
var history = scope.ServiceProvider.GetRequiredService<IMessageRepository>();
var page = await history.GetPageAsync(chats.Items[0].Chat.Id, before: null, after: null, limit: 2);
while (true)
{
Console.WriteLine($"Page: {string.Join(", ", page.Items.Select(m => m.Body))}");
if (page.NextCursor is null) break;
page = await history.GetPageAsync(chats.Items[0].Chat.Id, before: page.NextCursor, after: null, limit: 2);
}
}#:property PublishAot=false потрібне, бо .NET 10 за замовчуванням компілює програми з одного файлу для Native AOT, а EF Core не може побудувати свою модель у цьому режимі. Переконайтеся, що база даних працює (./Run.ps1 db у репозиторії), а потім:
powershell
dotnet run data.csПеревірка
Create alice: True
Create bob: True
Saved 8 rows; chat created at 20:18:42
Chat with bob: 3 unread, last: Message 5
Page: Message 5, Message 4
Page: Message 3, Message 2
Page: Message 1- 8 рядків: чат, два учасники й п’ять повідомлень, збережені одним
SaveChangesAsync. Alice й Bob збережено раніше, черезUserManager. - Чат отримав свій
CreatedAt(ваш час відрізнятиметься) від перехоплювача – програма його ніколи не задавала. - 3 непрочитані для Alice: повідомлення 1, 3 і 5 – від Bob, її власні повідомлення 2 і 4 не рахуються.
- Історія повертається від найновішого до найстарішого сторінками по два, а остання сторінка не має наступного курсора.
Програма створює користувачів із фіксованими іменами, тож другий запуск завершується помилкою: Create alice: False (ім’я зайняте), а потім SaveChangesAsync викидає DbUpdateException, бо новий чат посилається на ідентифікатор Alice, якої так і не збережено, – порушення зовнішнього ключа. Перед повторним запуском очистьте таблиці; truncate … cascade також очищає кожну таблицю, що посилається на користувачів:
powershell
docker compose exec postgres psql -U postgres -d chatex -c "truncate users cascade;"