// ==========================================================================================
// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
// 均受中华人民共和国及相关国际法律法规保护。
// are protected by the laws of the People's Republic of China and relevant international regulations.
// 使用本项目须严格遵守相应法律法规与开源许可证之规定。
// Usage of this project must strictly comply with applicable laws, regulations, and open-source licenses.
// 本项目采用 Apache License 2.0 单协议分发,
// This project is licensed solely under the Apache License 2.0,
// 完整许可证文本请参见源代码根目录下的 LICENSE 文件。
// please refer to the LICENSE file at the root directory of the source code for the full license text.
// 禁止利用本项目实施任何危害国家安全、破坏社会秩序、
// It is prohibited to use this project to engage in any activities that endanger national security, disrupt social order,
// 侵犯他人合法权益等法律法规所禁止的行为!
// or infringe upon the legitimate rights and interests of others, as prohibited by laws and regulations!
// 因基于本项目二次开发所产生的一切法律纠纷与责任,
// Any legal disputes and liabilities arising from secondary development based on this project
// 本项目组织与贡献者概不承担。
// shall be borne solely by the developer; the project organization and contributors assume no responsibility.
// GitHub 仓库:https://github.com/GameFrameX
// GitHub Repository: https://github.com/GameFrameX
// Gitee 仓库:https://gitee.com/GameFrameX
// Gitee Repository: https://gitee.com/GameFrameX
// CNB 仓库:https://cnb.cool/GameFrameX
// CNB Repository: https://cnb.cool/GameFrameX
// 官方文档:https://gameframex.doc.alianblank.com/
// Official Documentation: https://gameframex.doc.alianblank.com/
// ==========================================================================================
using System.Collections.Concurrent;
using System.Text.Json;
using GameFrameX.DataBase.Abstractions;
using GameFrameX.Foundation.Localization.Core;
using GameFrameX.Foundation.Utility;
using Microsoft.Data.Sqlite;
namespace GameFrameX.DataBase.Sqlite;
///
/// SQLite 嵌入式数据库服务(手写 ADO,无 EF)。
///
///
/// Embedded SQLite implementation of (hand-written ADO, no EF).
/// 存储模型 = PG StateRow 平移:每状态类型一张 (id INTEGER PRIMARY KEY, doc TEXT NOT NULL),
/// 状态对象经 System.Text.Json 与 doc 互转;查询为「id 等值提取下推 + 剩余 filter 客户端求值」,
/// 客户端求值下与手写 InMemory 的查询语义完全等同(C# 全语义)。
///
/// 边界(启动警告 Database.Provider.SqliteBoundaryWarning 同源,Amendment 3):
/// ① 复杂条件查询为客户端求值(可能全表扫描);② 写路径单连接串行;③ 拓扑边界为单进程
/// (跨进程发现/路由不可用,发现层由 InProcDiscoveryRuntime 以自指路由表替代);
/// ④ Availability 恒报 Healthy。生产规模化使用风险由使用方自担。
///
/// Degraded members (documented on purpose):
/// always reports (embedded
/// engine, no network partition semantics); data operations retry transient busy/locked/timeout failures
/// through the shared DbResilienceExecutor while the transaction shell stays single-pass
/// (ambient joins make blind retries unsafe); there is no background recovery task (a local file
/// either opens or fails fast during Open).
///
public sealed partial class SqliteDbService : IDatabaseService
{
///
/// 状态对象 ↔ doc 文本的 JSON 序列化选项(进程级单例,启用序列化器缓存)。
///
///
/// Process-wide JSON options for state ↔ doc text conversion (a single static instance
/// enables the serializer's metadata caching).
///
private static readonly JsonSerializerOptions DocumentJsonOptions = new()
{
IncludeFields = false,
};
///
/// 边界警告进程内只打一次的闸(控制库 + 业务库两次 Open 不刷屏,Amendment 3)。
///
///
/// Process-wide one-shot gate for the boundary warning so the control and business
/// database Opens do not print it twice.
///
private static int _boundaryWarningEmitted;
///
/// 单连接(:memory: 模式持连存活;文件模式 WAL)。所有操作经 串行复用。
///
///
/// The single connection (kept alive for :memory:; WAL journal mode for file databases).
/// Every operation reuses it under .
///
private SqliteConnection _connection;
///
/// 串行化闸(单连接上的读写互斥;事务持有期间嵌套操作直接放行)。
///
///
/// The serialization gate over the single connection; operations nested inside an ambient
/// transaction bypass the gate (they already run under it).
///
private readonly SemaphoreSlim _gate = new(1, 1);
///
/// 连接闸等待超时(闸被事务壳持有时,action 内 await 同实例不经环境事务放行的方法会不可重入死锁;限时转明确异常。测试缝可注入短值)。
///
///
/// How long any gate acquisition waits before failing with a descriptive
/// : while a transaction shell holds the gate, awaiting a
/// same-instance method that bypasses the ambient transaction (e.g. OpenAsync/CloseAsync)
/// deadlocks on the non-reentrant semaphore — the timeout converts that hang into a locating
/// error (default 30 seconds; instance-level internal seam so tests can inject a shorter value
/// without leaking into other service instances).
///
internal TimeSpan GateWaitTimeout { get; set; } = TimeSpan.FromSeconds(30);
///
/// 环境事务持有槽(事务壳持有 Holder:壳内嵌套操作/嵌套事务壳直接加入当前事务,不再重复拿闸/开事务;Holder 内字段 null = 无环境事务)。
///
///
/// Ambient-transaction slot held by the transaction shell: nested operations and nested
/// transaction shells inside an active shell join it instead of acquiring the gate / starting a
/// second transaction (SQLite cannot nest transactions on a single connection). The slot stores a
/// mutable holder (one per shell) instead of the raw transaction: derived async flows capture the
/// holder by reference, so clearing its field on shell exit is observed by every flow — a raw
/// AsyncLocal value would leave derived flows holding a disposed transaction.
/// Instance-level so concurrent service instances never cross-pollinate each other's shells.
///
private readonly AsyncLocal AmbientTransaction = new();
///
/// 环境事务持有对象(引用语义载体:事务壳清空内部字段后,所有派生异步流同步看到 null)。
///
///
/// Reference-semantics holder for the ambient transaction: the transaction shell clears the
/// field on exit, so every derived async flow sharing this holder
/// instance observes null immediately instead of retaining a disposed transaction snapshot in
/// its captured execution context.
///
private sealed class AmbientTransactionHolder
{
///
/// 当前环境事务(壳 finally 置 null,派生流据此判定无事务)。
///
///
/// The current ambient transaction (nulled by the shell's finally block; derived flows treat
/// null as "no ambient transaction").
///
public SqliteTransaction Transaction;
}
///
/// 表结构就绪缓存(表名 → 单飞建表任务;失败任务驱逐以便重试,对齐 PG 适配器语义)。
///
///
/// Table-readiness cache (table name to its single-flight DDL task); faulted tasks are
/// evicted so the next caller retries, aligned with the PostgreSQL adapter's semantics.
///
private readonly ConcurrentDictionary> _tableReady = new();
///
/// 状态类型 → 声明式唯一索引集缓存(进程级;反射结果只与类型相关,与连接/实例无关)。
///
///
/// Process-wide cache of state type to declared unique-index set. The reflected result depends only on
/// the type (never on the connection or the service instance), so one static cache serves every instance.
///
private static readonly ConcurrentDictionary UniqueIndexDeclarationCache = new();
///
/// 当前数据库配置选项(Open 成功后可用)。
///
///
/// The current database options (available after a successful Open).
///
private DbOptions _options;
///
/// 可用性状态(退化成员:嵌入式引擎无网络分区语义,恒报 )。
///
///
/// Degraded member: the embedded engine has no network-partition semantics, so this always
/// reports . Monitoring surfaces should not
/// treat SQLite as a remotely-failable dependency (boundary ④ of the startup warning).
///
public DatabaseAvailabilityState AvailabilityState => DatabaseAvailabilityState.Healthy;
///
/// 获取当前时间戳(毫秒,与 Mongo/PG 适配器逐字对齐)。
///
///
/// Gets the current timestamp in milliseconds, aligned verbatim with the Mongo / PostgreSQL
/// adapters ( selects the time-zone-offset variant).
///
/// 当前时间的 Unix 时间戳(毫秒)/ The current Unix timestamp in milliseconds
private long GetCurrentTimestamp()
{
if (_options.IsUseTimeZone)
{
return TimerHelper.UnixTimeMillisecondsWithTimeZoneOffset();
}
return TimerHelper.UnixTimeMilliseconds();
}
///
/// 校验连接已打开(未 Open 即调用读写为编程错误,启动路径 Open 失败即 fail-fast 不会到达这里)。
///
///
/// Guards that the connection is open. A read/write call before Open is a programming
/// error; the startup path fails fast inside Open and never reaches this state.
///
private void EnsureOpen()
{
if (_connection == null)
{
// Localization: Database.Sqlite.ServiceUnavailable - SqliteDbService 尚未打开(请先调用 Open)。
throw new DatabaseUnavailableException(LocalizationService.GetString(Localization.Keys.Database.Sqlite.ServiceUnavailable));
}
}
}