TCIS.EventBus.MultiTenancy 1.0.0

TCIS.EventBus.MultiTenancy

Cho consumer của TCIS.EventBus tự nạp hồ sơ tenant từ header t-site-code, để handler chạy được trên tầng dữ liệu đa cảng của TCIS.Pluggable.

Gói cầu nối: nó biết cả hai bên, để không bên nào phải biết bên kia. TCIS.EventBus giữ nguyên purity — chỉ tham chiếu TCIS.Core và TCIS.Logging.Abstractions.

Mục lục

1. Vấn đề nó giải
2. Cài đặt
3. Hành vi
4. Nó móc vào đâu, và vì sao đúng chỗ đó
5. Tự viết IConsumerContextInitializer
6. Những chỗ dễ vấp

1. Vấn đề nó giải

SubscribeExecutor khôi phục WorkContext từ header — đủ để định tuyến nghiệp vụ theo cảng (KeyedMediator chọn handler theo SiteCode), nhưng không đủ để mở kết nối.

Tầng dữ liệu đọc một nguồn khác: TenantConnectionSource và TenantFilterPolicy đều lấy TenantInfo từ IMultiTenantContextAccessor — nơi chứa chuỗi kết nối và mức cách ly. Consumer chạy trên thread nền của vòng lặp Kafka, không đi qua MultiTenantMiddleware, nên không thành phần nào nạp nó.

Vế thứ hai nguy hiểm hơn: hệ thống báo thành công sau khi không làm gì cả.

2. Cài đặt

dotnet add package TCIS.EventBus.MultiTenancy

// 1. Tenant Store — nguồn sự thật.
//    KHÔNG cần strategy: mã cảng đã có sẵn trong header, không cần cơ chế đi tìm nó.
builder.Services.AddTMultiTenant<TenantInfo>()
                .WithConfigurationStore();

// 2. EventBus như bình thường
builder.Services.AddTEventBus(o =>
{
    o.DefaultGroupName = "tcis.queue.berth-service";
    o.UseInMemoryStorage();
    o.UseKafka(k => k.Servers = "…");
})
.AddSubscriberAssembly(typeof(Program).Assembly);

// 3. Cầu nối
builder.Services.AddTEventBusTenantContext();

Host đơn tenant không gọi dòng 3, và EventBus hoạt động y hệt như trước: không có hiện thực IConsumerContextInitializer nào thì vòng lặp trong SubscribeInvoker không chạy lần nào.

Dùng kiểu TenantInfo dẫn xuất thì gọi overload generic:

builder.Services.AddTEventBusTenantContext<MyTenantInfo>();

3. Hành vi

// Trạm tích hợp chỉ chuyển tiếp dữ liệu, không chạm DB đa cảng:
builder.Services.AddTEventBusTenantContext(o => o.RequireTenant = false);

Lỗi cấu hình được phân loại vĩnh viễn: SubscribeExecutor.IsPermanentFailure nhận ra tiền tố SEC_ và CONFIG_, nên message hỏng vì cấu hình không chạy đủ FailedRetryCount vòng.

4. Nó móc vào đâu, và vì sao đúng chỗ đó

SubscribeInvoker gọi initializer giữa CreateAsyncScope() và GetInstance() — sau khi có scope, nhưng trước khi subscriber và mọi dependency của nó được dựng.

CreateAsyncScope() → ResolveAsync → Apply → GetInstance() → handler → finally: Cleanup()

Thứ tự này là điều kiện đúng đắn: DbContext chọn chuỗi kết nối theo tenant ngay trong constructor. Chuẩn bị ngữ cảnh sau GetInstance là quá muộn.

Cleanup() luôn chạy, kể cả khi handler ném, và theo thứ tự ngược với khởi tạo.

5. Tự viết IConsumerContextInitializer

Hợp đồng IConsumerContextInitializer nằm trong TCIS.EventBus và cố ý không biết chữ "tenant" — bạn có thể viết hiện thực cho feature flag, ngôn ngữ, hay bất cứ ngữ cảnh nào khác. Nhiều hiện thực cùng đăng ký thì chạy theo thứ tự đăng ký.

Hai ràng buộc bắt buộc:

5.1. Apply KHÔNG được là async

Ngữ cảnh nằm trong AsyncLocal, mà AsyncLocal chảy xuôi theo ExecutionContext chứ không chảy ngược: ghi nó sau một await đã thực sự nhường luồng thì thay đổi biến mất khi hàm trả về.

Đó là lý do hợp đồng tách đôi — ResolveAsync làm mọi việc cần await (tra store, gọi mạng) và không đụng tới ngữ cảnh; Apply chỉ ghi, và chạy trọn vẹn đồng bộ.

Hỏng không tất định: store trả kết quả đồng bộ (cache nóng) thì thay đổi lan ra bình thường. Chạy đúng trên máy dev, hỏng lần đầu gặp cache lạnh trên production.

5.2. Fail-closed là trách nhiệm của bên hiện thực

Thư viện không áp đặt chính sách. Ngữ cảnh là bắt buộc mà chuẩn bị không được thì ném từ Apply — message khi đó đi vào nhánh lỗi bình thường của consumer (có log, chuyển Failed) thay vì chạy nghiệp vụ với ngữ cảnh thiếu.

6. Những chỗ dễ vấp

Chi tiết vận hành: md/16 §6. Bộ test đối chứng: TCIS.EventBus.SiteRouting.Tests (Platform + hai Plugin ở ba assembly riêng, ba cảng ba tier, không cần Docker).