SPB Git

Repository Public

NotesStore.swift 15.1 KB 362 lines swift

1// SP Notes Core2// File: Sources/SPNotesStore/NotesStore.swift3// Description: The store actor: opening, transactions, change notification, meta key/value, maintenance,4//              and the row helpers shared by the feature extensions.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910/// The durable local database of the SP Notes apps. Every access is serialized by the actor; every mutation is11/// one atomic SQLite transaction and none waits for the network.12public actor NotesStore {13    let db: Database14    public nonisolated let isReadOnly: Bool15    /// What opening did: version found, migration, pre-migration backup made or removed (2.0).16    public nonisolated let openReport: StoreOpenReport1718    private var subscribers: [UUID: AsyncStream<StoreChange>.Continuation] = [:]19    var pending = PendingChanges()20    private var writeDepth = 02122    /// Events accumulated by a write transaction, published after it commits.23    struct PendingChanges {24        var pages: Set<String> = []25        var tags = false26        var attachments: Set<String> = []27        var queue = false28        var conflicts = false29        var reminders = false30        var meta: [String] = []31        var reset = false32        var entities: [String: Set<String>] = [:]33        var entityQueue = false34        var canvases: Set<String> = []35        var events = false36        var cache: [String] = []37    }3839    // MARK: Opening4041    /// Opens (creating and migrating it when writable) the database file at `url`.42    /// A read-only connection never creates nor migrates: it throws `StoreError.schema` on an outdated file.43    public init(url: URL, readOnly: Bool = false) throws {44        try self.init(path: url.path, readOnly: readOnly)45    }4647    init(path: String, readOnly: Bool, backupRetention: TimeInterval = StoreBackup.defaultRetention) throws {48        let db = try Database(path: path, readOnly: readOnly)49        var report = StoreOpenReport(schemaVersion: Schema.currentVersion)50        do {51            if !readOnly, path != ":memory:" { try StoreBackup.prepare(db, path: path, retention: backupRetention, report: &report) }52            try Schema.migrate(db)53        } catch {54            db.close()55            throw error56        }57        self.db = db58        self.isReadOnly = readOnly59        self.openReport = report60    }6162    /// A private in-memory store (tests, previews).63    public static func inMemory() throws -> NotesStore {64        try NotesStore(path: ":memory:", readOnly: false)65    }6667    /// Closes the connection. Every later call throws `StoreError.closed`. Change streams finish.68    public func close() {69        db.close()70        for continuation in subscribers.values { continuation.finish() }71        subscribers.removeAll()72    }7374    public static var schemaVersion: Int { Schema.currentVersion }7576    // MARK: Transactions7778    /// Runs a mutation atomically, then publishes the changes it recorded. On error nothing is written and79    /// nothing is published.80    func write<T>(_ body: () throws -> T) throws -> T {81        guard !isReadOnly else { throw StoreError.readOnly }82        if writeDepth > 0 { return try db.transaction(body) }83        pending = PendingChanges()84        writeDepth += 185        defer { writeDepth -= 1 }86        do {87            let result = try db.transaction(body)88            publish()89            return result90        } catch {91            pending = PendingChanges()92            throw error93        }94    }9596    /// Runs several reads on one consistent snapshot.97    func read<T>(_ body: () throws -> T) throws -> T {98        if db.inTransaction { return try body() }99        return try db.transaction(immediate: false, body)100    }101102    // MARK: Change notification103104    /// A stream of what changed, published after each committed mutation of THIS store instance.105    /// Any number of subscribers; each gets every event (unbounded buffer). Changes written by another process106    /// (share extension) are not observed: relay them with `noteExternalChange()`.107    public func changes() -> AsyncStream<StoreChange> {108        let id = UUID()109        let (stream, continuation) = AsyncStream<StoreChange>.makeStream()110        subscribers[id] = continuation111        continuation.onTermination = { [weak self] _ in112            Task { await self?.unsubscribe(id) }113        }114        return stream115    }116117    private func unsubscribe(_ id: UUID) {118        subscribers.removeValue(forKey: id)119    }120121    /// Tells subscribers that another process modified the file (emits `.reset`).122    public func noteExternalChange() {123        emit(.reset)124    }125126    private func emit(_ change: StoreChange) {127        for continuation in subscribers.values { continuation.yield(change) }128    }129130    private func publish() {131        let changes = pending132        pending = PendingChanges()133        guard !subscribers.isEmpty else { return }134        if changes.reset { emit(.reset) }135        if !changes.pages.isEmpty { emit(.pages(changes.pages)) }136        if changes.tags { emit(.tags) }137        if !changes.attachments.isEmpty { emit(.attachments(changes.attachments)) }138        if changes.queue { emit(.queue) }139        if changes.conflicts { emit(.conflicts) }140        if changes.reminders { emit(.reminders) }141        for key in changes.meta { emit(.meta(key)) }142        for kind in changes.entities.keys.sorted() { emit(.entities(kind: kind, ids: changes.entities[kind] ?? [])) }143        if changes.entityQueue { emit(.entityQueue) }144        if !changes.canvases.isEmpty { emit(.canvases(changes.canvases)) }145        if changes.events { emit(.events) }146        for key in changes.cache { emit(.cache(key)) }147    }148149    // MARK: Meta150151    public static let syncCursorKey = "sync.cursor"152153    public func meta(_ key: String) throws -> String? {154        try db.first("SELECT value FROM meta WHERE key=?", [key]) { $0.string(0) }155    }156157    /// Sets (or removes, with nil) a key.158    public func setMeta(_ key: String, _ value: String?) throws {159        try write { try putMeta(key, value) }160    }161162    public func allMeta() throws -> [String: String] {163        var out: [String: String] = [:]164        _ = try db.query("SELECT key, value FROM meta") { out[$0.string(0)] = $0.string(1) }165        return out166    }167168    func putMeta(_ key: String, _ value: String?) throws {169        if let value {170            try db.run("INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value", [key, value])171        } else {172            try db.run("DELETE FROM meta WHERE key=?", [key])173        }174        pending.meta.append(key)175    }176177    /// The server change sequence up to which the feed was applied (0 = never synced).178    public func syncCursor() throws -> Int64 {179        Int64(try meta(Self.syncCursorKey) ?? "") ?? 0180    }181182    public func setSyncCursor(_ cursor: Int64) throws {183        try setMeta(Self.syncCursorKey, String(cursor))184    }185186    // MARK: Maintenance187188    /// Runs `PRAGMA integrity_check` and `PRAGMA foreign_key_check`. Returns the problems found (empty = healthy).189    public func integrityCheck() throws -> [String] {190        var problems = try db.query("PRAGMA integrity_check") { $0.string(0) }.filter { $0 != "ok" }191        problems += try db.query("PRAGMA foreign_key_check") { "foreign key violation in \($0.string(0))" }192        return problems193    }194195    /// Moves the write-ahead log into the main file and truncates it.196    public func checkpoint() throws {197        guard !isReadOnly else { throw StoreError.readOnly }198        _ = try db.query("PRAGMA wal_checkpoint(TRUNCATE)") { $0.int(0) }199    }200201    /// Rebuilds the full-text index from the pages table.202    public func rebuildSearchIndex() throws {203        try write {204            try db.run("DELETE FROM pages_fts")205            try db.run("""206            INSERT INTO pages_fts(rowid, title, body, tags)207            SELECT rid, title, plain_text, coalesce((SELECT group_concat(name, ' ') FROM page_tags WHERE page_rid=rid), '') FROM pages208            """)209        }210    }211212    /// Erases every row of every table, including meta. Only for an explicit "erase this device" action.213    /// Attachment files are the caller's to delete.214    public func wipeAll() throws {215        try write {216            for table in Schema.v2Tables + ["pages_fts", "page_tags", "page_bases", "conflicts", "local_versions", "reminders", "attachments", "ops", "tags", "meta", "pages"] {217                try db.run("DELETE FROM \(table)")218            }219            pending.reset = true220        }221        try? checkpoint()222    }223224    /// Diagnostics and tests: the first column of the first row of a read-only statement, as text.225    func debugValue(_ sql: String) throws -> String? {226        try db.first(sql) { $0.optString(0) } ?? nil227    }228229    /// Diagnostics and tests: the query plan of a statement, one step per line.230    func queryPlan(_ sql: String) throws -> String {231        try db.query("EXPLAIN QUERY PLAN " + sql) { $0.string(3) }.joined(separator: "\n")232    }233234    // MARK: Shared helpers235236    static func newId() -> String { UUID().uuidString.lowercased() }237238    func nowMillis() -> Int64 { Date().millis }239240    static let pageColumns = """241    p.rid, p.id, p.parent_id, p.database_id, p.type, p.section, p.title, p.icon, p.cover, p.content, p.properties, p.position, \242    p.pinned, p.archived, p.server_version, p.word_count, p.created_at, p.updated_at, p.last_opened_at, p.deleted_at, p.inbox_at, \243    p.capture_kind, p.rev, p.needs_create, p.dirty_content, p.dirty_meta, p.tags_dirty, p.edit_seq, p.sync_state, p.sync_error, \244    p.plain_text, p.preview, p.favorite, p.is_folder, p.local_updated_at, \245    (SELECT group_concat(name, char(31)) FROM (SELECT name FROM page_tags WHERE page_rid=p.rid ORDER BY name))246    """247248    typealias LoadedPage = (rid: Int64, page: PageRecord)249250    static func decodeTags(_ joined: String?) -> [String] {251        guard let joined, !joined.isEmpty else { return [] }252        return joined.split(separator: "\u{1F}").map(String.init)253    }254255    static func decodeMeta(_ joined: String) -> Set<MetaField> {256        Set(joined.split(separator: ",").compactMap { MetaField(rawValue: String($0)) })257    }258259    static func encodeMeta(_ fields: Set<MetaField>) -> String {260        fields.map(\.rawValue).sorted().joined(separator: ",")261    }262263    static func decodePage(_ r: Row) -> LoadedPage {264        let page = PageRecord(265            id: r.string(1), parentId: r.optString(2), databaseId: r.optString(3), type: r.string(4), section: r.string(5),266            title: r.string(6), icon: r.optString(7), cover: r.optString(8), content: r.data(9), properties: r.data(10),267            position: r.double(11), pinned: r.bool(12), archived: r.bool(13), serverVersion: Int(r.int(14)),268            wordCount: Int(r.int(15)), createdAt: r.date(16), updatedAt: r.date(17), lastOpenedAt: r.optDate(18),269            deletedAt: r.optDate(19), inboxAt: r.optDate(20), captureKind: r.optString(21), rev: r.int(22),270            tags: decodeTags(r.optString(35)), needsCreate: r.bool(23), dirtyContent: r.bool(24),271            dirtyMeta: decodeMeta(r.string(25)), tagsDirty: r.bool(26), editSeq: r.int(27),272            syncState: SyncState(rawValue: r.string(28)) ?? .synced, syncError: r.optString(29), plainText: r.string(30),273            preview: r.string(31), favorite: r.bool(32), isFolder: r.bool(33), localUpdatedAt: r.date(34))274        return (r.int(0), page)275    }276277    func loadPage(_ id: String) throws -> LoadedPage? {278        try db.first("SELECT \(Self.pageColumns) FROM pages p WHERE p.id=?", [id], Self.decodePage)279    }280281    func requirePage(_ id: String) throws -> LoadedPage {282        guard let loaded = try loadPage(id) else { throw StoreError.notFound("page \(id)") }283        return loaded284    }285286    func loadBase(_ id: String) throws -> PageBase? {287        try db.first("SELECT title, content, properties, version FROM page_bases WHERE page_id=?", [id]) {288            PageBase(title: $0.string(0), content: $0.data(1), properties: $0.data(2), version: Int($0.int(3)))289        }290    }291292    /// Keeps the last synced copy the first time a synced page gets a local content edit. Call BEFORE the edit.293    func captureBase(_ id: String) throws {294        try db.run("""295        INSERT OR IGNORE INTO page_bases(page_id, title, content, properties, version)296        SELECT id, title, content, properties, server_version FROM pages WHERE id=? AND dirty_content=0 AND needs_create=0 AND server_version>0297        """, [id])298    }299300    /// Recomputes `sync_state` from the flags (conflict > error > pending > synced).301    func refreshState(_ id: String) throws {302        try db.run("""303        UPDATE pages SET304            sync_error = CASE WHEN \(Schema.dirtyPredicate) THEN sync_error ELSE NULL END,305            sync_state = CASE306                WHEN EXISTS(SELECT 1 FROM conflicts c WHERE c.page_id=pages.id) THEN 'conflict'307                WHEN \(Schema.dirtyPredicate) THEN (CASE WHEN sync_error IS NOT NULL THEN 'error' ELSE 'pending' END)308                ELSE 'synced' END309        WHERE id=?310        """, [id])311    }312313    /// Re-indexes one page in the full-text index (delete by rowid, then insert).314    func reindex(_ rid: Int64) throws {315        try db.run("DELETE FROM pages_fts WHERE rowid=?", [rid])316        try db.run("""317        INSERT INTO pages_fts(rowid, title, body, tags)318        SELECT rid, title, plain_text, coalesce((SELECT group_concat(name, ' ') FROM page_tags WHERE page_rid=rid), '') FROM pages WHERE rid=?319        """, [rid])320    }321322    /// Ids of a page and all its descendants (cycle-safe). With `liveOnly`, the walk does not enter trashed children.323    func subtreeIds(_ id: String, liveOnly: Bool = false) throws -> [String] {324        try db.query("""325        WITH RECURSIVE sub(id) AS (326            VALUES(?)327            UNION328            SELECT p.id FROM pages p JOIN sub ON p.parent_id=sub.id\(liveOnly ? " WHERE p.deleted_at IS NULL" : "")329        ) SELECT id FROM sub330        """, [id]) { $0.string(0) }331    }332}333334// MARK: - JSON helpers for the properties object335336enum PropertiesJSON {337    static func object(_ data: Data) -> [String: Any]? {338        (try? JSONSerialization.jsonObject(with: data)) as? [String: Any]339    }340341    /// (favorite, folder) read from the top level of the properties object; nil when it is not a JSON object.342    static func flags(_ data: Data) -> (favorite: Bool, folder: Bool)? {343        guard let object = object(data) else { return nil }344        return ((object["favorite"] as? Bool) == true, (object["folder"] as? Bool) == true)345    }346347    /// Returns the properties with a boolean flag set (true) or removed (false).348    static func setting(_ data: Data, key: String, to value: Bool) throws -> Data {349        guard var object = object(data) else { throw StoreError.invalid("properties is not a JSON object") }350        if value { object[key] = true } else { object.removeValue(forKey: key) }351        return try JSONSerialization.data(withJSONObject: object, options: [.sortedKeys])352    }353354    /// Key-order independent equality.355    static func equal(_ a: Data, _ b: Data) -> Bool {356        if a == b { return true }357        guard let x = try? JSONSerialization.jsonObject(with: a, options: [.fragmentsAllowed]) as? NSObject,358              let y = try? JSONSerialization.jsonObject(with: b, options: [.fragmentsAllowed]) as? NSObject else { return false }359        return x.isEqual(y)360    }361}362
Files main
Menu

Theme