cj-tauri 0.8.0 → 1.1.0

package/src/plugins/sqlite/sqlite_ffi.cj

@@ -0,0 +1,206 @@
+package cjTauri.plugins.sqlite
+
+import cjTauri.*
+
+/**
+ * SQLite C API 的 FFI 声明与最小包装（`sqlite` 插件的地基）
+ *
+ * **为什么直连系统库而不进 C 桥**（docs/设计决策记录.md D-018 第 2 条）：现有 `cj_bridge_*` 之所以存在，
+ * 是因为平台差异集中在 C 桥里；SQLite 相反——三平台同一套 C API、没有平台分支，再包一层只是多一份要
+ * 维护的转发代码。代价是「链接谁」从「桥提供」变成「消费方各自提供」：Linux 链发行版系统库
+ * （`-lsqlite3`，本机 3.45.1），Windows 侧未落地（见 D-018 第 8 条）。
+ *
+ * **FFI 语法是实测出来的**（三条都进 AGENTS §4）：
+ *   1. 仓颉**没有** `&x` 取地址（写它会报 `expected expression after ','`）；C 出参在**调用处**写
+ *      `inout <var>`，自动取址成 `CPointer<T>`——修饰对象只能是 `var`，且指针仅在本次调用期间有效。
+ *   2. 「可选传 NULL 的 C 字符串」（这里的 `zVfs`）声明成 `CPointer<UInt8>` 并传 `CPointer<UInt8>()`；
+ *      传空 `CString` 会被 SQLite 当成「名字为空的 VFS」，报的是 `no such vfs`（实测踩过）。
+ *   3. C 回调声明成 `CFunc<(...) -> 返回类型>`，回调本体是顶层 `@C func`（本仓 `cj_bridge_init` 先例）。
+ */
+
+/** SQLite 返回码（sqlite3.h 的子集，只列我们判过的） */
+let SQLITE_OK: Int32 = 0
+let SQLITE_ROW: Int32 = 100
+let SQLITE_DONE: Int32 = 101
+/** sqlite3_exec 在授权回调拒绝时给的是 SQLITE_AUTH（列出来便于断言时看明白） */
+let SQLITE_AUTH: Int32 = 23
+
+/** 列类型（sqlite3_column_type）：界面要能说清「这格是数字还是文本」，所以逐格判 */
+let SQLITE_INTEGER: Int32 = 1
+let SQLITE_FLOAT: Int32 = 2
+let SQLITE_TEXT: Int32 = 3
+let SQLITE_BLOB: Int32 = 4
+let SQLITE_NULL: Int32 = 5
+
+/** 打开标志（sqlite3_open_v2）：只读走 READONLY，写路径要显式给 READWRITE */
+let SQLITE_OPEN_READONLY: Int32 = 1
+let SQLITE_OPEN_READWRITE: Int32 = 2
+let SQLITE_OPEN_CREATE: Int32 = 4
+
+/** 授权动作码（sqlite3_set_authorizer）：只列我们要拒的三类 */
+let SQLITE_ATTACH: Int32 = 24
+let SQLITE_DETACH: Int32 = 25
+let SQLITE_FUNCTION: Int32 = 31
+
+/** 授权回调返回值 */
+let SQLITE_DENY: Int32 = 1
+
+/** busy 等待上限（毫秒）：另一个进程正写这个库时等着，而不是当场报 SQLITE_BUSY */
+let SQLITE_BUSY_TIMEOUT_MS: Int32 = 3000
+
+@C
+foreign func sqlite3_libversion(): CString
+
+@C
+foreign func sqlite3_open_v2(filename: CString, ppDb: CPointer<CPointer<Unit>>, flags: Int32,
+                             zVfs: CPointer<UInt8>): Int32
+
+@C
+foreign func sqlite3_close(db: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_errmsg(db: CPointer<Unit>): CString
+
+@C
+foreign func sqlite3_exec(db: CPointer<Unit>, sql: CString, cb: CPointer<Unit>, arg: CPointer<Unit>,
+                          errmsg: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_changes(db: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_last_insert_rowid(db: CPointer<Unit>): Int64
+
+@C
+foreign func sqlite3_busy_timeout(db: CPointer<Unit>, ms: Int32): Int32
+
+@C
+foreign func sqlite3_prepare_v2(db: CPointer<Unit>, sql: CString, nByte: Int32,
+                                ppStmt: CPointer<CPointer<Unit>>, pzTail: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_step(stmt: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_finalize(stmt: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_column_count(stmt: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_column_name(stmt: CPointer<Unit>, i: Int32): CString
+
+@C
+foreign func sqlite3_column_type(stmt: CPointer<Unit>, i: Int32): Int32
+
+@C
+foreign func sqlite3_column_int64(stmt: CPointer<Unit>, i: Int32): Int64
+
+@C
+foreign func sqlite3_column_double(stmt: CPointer<Unit>, i: Int32): Float64
+
+@C
+foreign func sqlite3_column_text(stmt: CPointer<Unit>, i: Int32): CString
+
+@C
+foreign func sqlite3_column_bytes(stmt: CPointer<Unit>, i: Int32): Int32
+
+@C
+foreign func sqlite3_set_authorizer(
+    db: CPointer<Unit>,
+    cb: CFunc<(CPointer<Unit>, Int32, CString, CString, CString, CString) -> Int32>,
+    userdata: CPointer<Unit>): Int32
+
+@C
+foreign func sqlite3_enable_load_extension(db: CPointer<Unit>, onoff: Int32): Int32
+
+/**
+ * 授权回调：拒掉「跑到别的文件去」的动作——`ATTACH` / `DETACH` 换库文件、
+ * `load_extension()` 加载任意原生库。**必须按语句判**：路径 scope 只管得住本次命令收到的那个路径，
+ * 管不住 SQL 里写死的另一个路径（D-018 第 4 条）。被拒时留一行 stderr，取证时能对上账。
+ */
+@C
+func sqliteAuthorizer(app: CPointer<Unit>, code: Int32, arg1: CString, arg2: CString,
+                      dbName: CString, triggerName: CString): Int32 {
+    let _ = app
+    let _ = arg2
+    let _ = dbName
+    let _ = triggerName
+    if (code == SQLITE_ATTACH || code == SQLITE_DETACH) {
+        eprintln("[cj-tauri] sqlite denied: attach/detach is not allowed (code=${code})")
+        return SQLITE_DENY
+    }
+    if (code == SQLITE_FUNCTION) {
+        // arg1 是被调用的函数名：只拒能加载原生代码的那个，其余内置函数照常放行
+        let fnName = sqliteCString(arg1)
+        if (fnName == "load_extension") {
+            eprintln("[cj-tauri] sqlite denied: load_extension() is not allowed")
+            return SQLITE_DENY
+        }
+    }
+    return SQLITE_OK
+}
+
+/** C 字符串 → 仓颉字符串；NULL 给空串（调用方要区分 NULL 与空串时另判归属） */
+func sqliteCString(s: CString): String {
+    if (s.isNull()) {
+        return ""
+    }
+    return s.toString()
+}
+
+/** 取最近一次错误文案；db 为空时给固定文案，避免收尾路径上再炸一次 */
+func sqliteLastError(db: CPointer<Unit>): String {
+    if (db.isNull()) {
+        return "unknown error (null db handle)"
+    }
+    return sqliteCString(unsafe { sqlite3_errmsg(db) })
+}
+
+/** 关掉句柄：对空指针安全（出错路径也要能收尾），关不掉只记一行 stderr 不抛 */
+func sqliteCloseQuietly(db: CPointer<Unit>): Unit {
+    if (db.isNull()) {
+        return
+    }
+    let rc = unsafe { sqlite3_close(db) }
+    if (rc != SQLITE_OK) {
+        eprintln("[cj-tauri] sqlite close returned ${rc}")
+    }
+}
+
+/**
+ * 打开数据库并装上护栏（每次命令短连接，见 D-018 第 9 条）。
+ *
+ * `readonly=true` 走 `SQLITE_OPEN_READONLY`——只读是**内核级**的，不是我们写的检查；
+ * 不存在的文件 + 只读 = 打开失败（不会顺手造一个空库）。
+ * 打开失败与护栏装不上都抛 `CommandException`（前端拿到可读文案）。
+ */
+func sqliteOpenGuarded(path: String, readonly: Bool): CPointer<Unit> {
+    var db: CPointer<Unit> = CPointer<Unit>()
+    let flags = if (readonly) {
+        SQLITE_OPEN_READONLY
+    } else {
+        SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
+    }
+    // inout db 取的是「栈上那个指针变量」的地址：C 侧写入的 handle 直接落到 db 上
+    let rc = unsafe { sqlite3_open_v2(LibC.mallocCString(path), inout db, flags, CPointer<UInt8>()) }
+    if (rc != SQLITE_OK) {
+        let msg = sqliteLastError(db)
+        sqliteCloseQuietly(db)
+        throw CommandException("sqlite: cannot open ${path}: ${msg}")
+    }
+    // 双保险之一：先关掉扩展加载（authorizer 之外再加一道）
+    let _ = unsafe { sqlite3_enable_load_extension(db, 0) }
+    let rcAuthorizer = unsafe { sqlite3_set_authorizer(db, sqliteAuthorizer, CPointer<Unit>()) }
+    if (rcAuthorizer != SQLITE_OK) {
+        sqliteCloseQuietly(db)
+        throw CommandException("sqlite: cannot install authorizer (rc=${rcAuthorizer})")
+    }
+    let _ = unsafe { sqlite3_busy_timeout(db, SQLITE_BUSY_TIMEOUT_MS) }
+    return db
+}
+
+/** 本机链接的 SQLite 版本（`sqlite:info` 回投给页面，对账时也用它） */
+func sqliteLibVersion(): String {
+    return sqliteCString(unsafe { sqlite3_libversion() })
+}

package/src/plugins/store/plugin_store.cj

@@ -0,0 +1,287 @@
+package cjTauri.plugins.store
+
+import cjTauri.*
+
+import std.collection.*
+import std.fs.*
+import std.sync.*
+import stdx.encoding.json.*
+
+/**
+ * 官方插件 store：持久化键值存储（纯仓颉，零 C 桥；RFC-003 第 2 期，对标 tauri-plugin-store）
+ *
+ * 命令：store:get / store:set / store:delete / store:keys / store:clear
+ * 权限：**不自动放行**，应用要在 capabilities 里显式声明，两种写法等价：
+ *   "commands": ["store:get", "store:keys"]     // 明文逐条
+ *   "permissions": ["store:readonly"]           // 命名权限集（get + keys，一次放行读那组）
+ * 前端：window.__CJ_TAURI__.store.set({ key: "theme", value: "dark" })
+ *
+ * 值是**任意 JSON**（对象/数组/标量都行）——落盘形状就是 `{ key: value, ... }` 一个 JSON 对象。
+ * 落盘位置：`StorePlugin()` 默认 `<工作目录>/store.json`（与 capabilities/ 同一套项目根约定），
+ * `StorePlugin(path)` 自定义。v1 一应用一个 store（插件按 name 装配，多实例会撞名）。
+ *
+ * 原子写：先写 `path.tmp` 再 `rename(overwrite: true)`，进程中途被杀也不会留下半个 JSON；
+ * rename 失败回落直写并打 stderr（与 examples/music 的手搓存储同级兜底）。
+ * 损坏文件不是致命错误：读失败一行 stderr + 从空开始，下次 save 覆盖掉坏文件。
+ */
+public class StorePlugin <: Plugin {
+    private let store: StoreBackend
+
+    public init() {
+        this.store = StoreBackend("store.json")
+    }
+
+    public init(path: String) {
+        this.store = StoreBackend(path)
+    }
+
+    public func name(): String {
+        return "store"
+    }
+
+    public func commands(): HashMap<String, CommandHandler> {
+        let m = HashMap<String, CommandHandler>()
+        m.add("get", StoreCommands(this.store))
+        m.add("set", StoreCommands(this.store))
+        m.add("delete", StoreCommands(this.store))
+        m.add("keys", StoreCommands(this.store))
+        m.add("clear", StoreCommands(this.store))
+        return m
+    }
+
+    /**
+     * 命名权限集：readonly 只含「读」两条（get + keys）——只想读的应用引用它即可，
+     * **写能力不会被顺带打开**；要写必须显式引用 default 或把写命令写成明文。
+     */
+    public func permissions(): HashMap<String, ArrayList<String>> {
+        let m = HashMap<String, ArrayList<String>>()
+        let ro = ArrayList<String>()
+        ro.add("get")
+        ro.add("keys")
+        m.add("readonly", ro)
+        let all = ArrayList<String>()
+        all.add("get")
+        all.add("set")
+        all.add("delete")
+        all.add("keys")
+        all.add("clear")
+        m.add("default", all)
+        return m
+    }
+
+    /**
+     * 前端 shim：只往 __CJ_TAURI__ 挂一个 store 命名空间，不动 invoke / listen / emit
+     */
+    public func jsShim(): String {
+        return "(function () { var t = window.__CJ_TAURI__ || (window.__CJ_TAURI__ = {});" +
+            " t.store = {" +
+            " get: function (a) { return window.__CJ_TAURI__.invoke('store:get', a); }," +
+            " set: function (a) { return window.__CJ_TAURI__.invoke('store:set', a); }," +
+            " del: function (a) { return window.__CJ_TAURI__.invoke('store:delete', a); }," +
+            " keys: function () { return window.__CJ_TAURI__.invoke('store:keys', {}); }," +
+            " clear: function () { return window.__CJ_TAURI__.invoke('store:clear', {}); }" +
+            " }; })();\n"
+    }
+}
+
+/**
+ * 存储本体：内存 JsonObject + 锁 + 原子落盘。
+ *
+ * 独立成类而不是塞进命令处理器里：五条命令共享同一份内存与文件（命令处理器是按命令各 new 的），
+ * 单测也要能直接驱动它（并发写 / 损坏文件回落都不必过 IPC）。
+ */
+public class StoreBackend {
+    private var path: String
+    private var root: JsonObject
+    // 命令跑在 worker 线程上：内存对象与「读-改-写盘」必须整块互斥，否则并发 set 会互相覆盖
+    private let lock: Mutex = Mutex()
+
+    public init(path: String) {
+        this.path = path
+        this.root = JsonObject()
+        this.load()
+    }
+
+    public func pathOf(): String {
+        return this.path
+    }
+
+    /** 读盘：读不到（第一次跑）与读坏都不是致命错误——后者一行 stderr 再从空开始（music 先例） */
+    private func load(): Unit {
+        try {
+            let text = String.fromUtf8(File.readFrom(this.path))
+            let parsed = JsonValue.fromStr(text)
+            match (parsed.kind()) {
+                case JsonKind.JsObject => this.root = parsed.asObject()
+                case _ => eprintln("[cj-tauri] store 文件不是 JSON 对象，本轮从空开始：${this.path}")
+            }
+        } catch (e: Exception) {
+            // 第一次跑就是这条路径——没有 store 文件是正常状态，不是错误
+        }
+    }
+
+    /**
+     * 原子落盘：写 tmp → rename 覆盖。rename 失败回落直写（保住「能存上」这个主目标），
+     * 两种失败都留 stderr——写盘失败必须可观测，不能让「本轮只在内存里」无声发生。
+     */
+    private func saveLocked(): Bool {
+        let text = this.root.toJsonString()
+        let tmp = this.path + ".tmp"
+        try {
+            File.writeTo(tmp, text.toArray())
+            try {
+                rename(tmp, to: this.path, overwrite: true)
+            } catch (e: Exception) {
+                // rename 失败（跨目录/被占用等）：回落直写目标文件，别让数据丢在 tmp 里
+                File.writeTo(this.path, text.toArray())
+                eprintln("[cj-tauri] store 原子替换失败已回落直写：${e}")
+            }
+            return true
+        } catch (e: Exception) {
+            eprintln("[cj-tauri] store 写盘失败：${e}（路径 ${this.path}，本轮改动只在内存里）")
+            return false
+        }
+    }
+
+    /**
+     * 读一个键。缺失时：给了 default 回 default，没给回 JSON null
+     * （用 fromStr("null") 构造——JsonNull 的构造契约未在仓内核实过，不猜）。
+     */
+    public func get(key: String, hasDefault: Bool, defaultValue: JsonValue): JsonValue {
+        synchronized(this.lock) {
+            match (this.root.get(key)) {
+                case Some(v) => return v
+                case None =>
+                    if (hasDefault) {
+                        return defaultValue
+                    }
+                    return JsonValue.fromStr("null")
+            }
+        }
+    }
+
+    /** 写一个键并落盘；返回落盘是否成功（false = 本轮只在内存里，页面据此提示） */
+    public func set(key: String, value: JsonValue): Bool {
+        synchronized(this.lock) {
+            this.root.put(key, value)
+            return this.saveLocked()
+        }
+    }
+
+    /** 删一个键并落盘；返回 (是否存在过, 落盘是否成功)——页面据此区分「删了」与「本来就没有」 */
+    public func delete(key: String): (Bool, Bool) {
+        synchronized(this.lock) {
+            // getFields + HashMap.remove + 重建：不管 getFields 给的是拷贝还是内部表，结果都正确
+            let fields = this.root.getFields()
+            let removed = fields.remove(key)
+            this.root = JsonObject(fields)
+            if (removed.isNone()) {
+                return (false, true)
+            }
+            return (true, this.saveLocked())
+        }
+    }
+
+    /** 全部键，按字典序（输出稳定、可断言） */
+    public func keys(): ArrayList<String> {
+        synchronized(this.lock) {
+            let names = ArrayList<String>()
+            for ((k, _) in this.root.getFields()) {
+                names.add(k)
+            }
+            return sortedStrings(names)
+        }
+    }
+
+    /** 清空并落盘；返回清掉的键数与落盘是否成功 */
+    public func clear(): (Int64, Bool) {
+        synchronized(this.lock) {
+            let n = this.root.size()
+            this.root = JsonObject()
+            if (n == 0) {
+                return (0, true)
+            }
+            return (n, this.saveLocked())
+        }
+    }
+}
+
+/** store 的五条命令：分发 + 参数校验，逻辑都在 StoreBackend 里 */
+public class StoreCommands <: CommandHandler {
+    private let store: StoreBackend
+
+    public init(store: StoreBackend) {
+        this.store = store
+    }
+
+    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
+        let _ = ipc // store 的命令都是纯本地读写，不回头投事件，用不上上下文
+        match (cmd) {
+            case "store:get" => this.getCmd(args)
+            case "store:set" => this.setCmd(args)
+            case "store:delete" => this.deleteCmd(args)
+            case "store:keys" => this.keysCmd()
+            case "store:clear" => this.clearCmd()
+            case _ => throw CommandException("unknown store command: ${cmd}")
+        }
+    }
+
+    private func requireKey(args: JsonObject): String {
+        match (args.get("key")) {
+            case Some(v) =>
+                match (v.kind()) {
+                    case JsonKind.JsString =>
+                        let k = v.asString().getValue()
+                        if (k.isEmpty()) {
+                            throw CommandException("store: key 不能为空字符串")
+                        }
+                        return k
+                    case _ => throw CommandException("store: 参数 \"key\" 必须是字符串")
+                }
+            case None => throw CommandException("store: 缺少参数 \"key\"")
+        }
+    }
+
+    private func getCmd(args: JsonObject): JsonValue {
+        let key = this.requireKey(args)
+        match (args.get("default")) {
+            case Some(d) => return this.store.get(key, true, d)
+            case None => return this.store.get(key, false, JsonBool(false))
+        }
+    }
+
+    private func setCmd(args: JsonObject): JsonValue {
+        let key = this.requireKey(args)
+        // 值是任意 JSON；没传 value 视为编程错误直接拒（想存 null 就显式传 value: null）
+        match (args.get("value")) {
+            case Some(v) => return JsonBool(this.store.set(key, v))
+            case None => throw CommandException("store: 缺少参数 \"value\"（想存 null 就显式传 value: null）")
+        }
+    }
+
+    private func deleteCmd(args: JsonObject): JsonValue {
+        let key = this.requireKey(args)
+        let (existed, saved) = this.store.delete(key)
+        let out = JsonObject()
+        out.put("existed", JsonBool(existed))
+        out.put("saved", JsonBool(saved))
+        return out
+    }
+
+    private func keysCmd(): JsonValue {
+        let names = this.store.keys()
+        let arr = ArrayList<JsonValue>()
+        for (k in names) {
+            arr.add(JsonString(k))
+        }
+        return JsonArray(arr)
+    }
+
+    private func clearCmd(): JsonValue {
+        let (cleared, saved) = this.store.clear()
+        let out = JsonObject()
+        out.put("cleared", JsonInt(cleared))
+        out.put("saved", JsonBool(saved))
+        return out
+    }
+}