// ========================================================================================== // 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)); } } }