Repository Public
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