Repository Public MIT
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX Astra9// File : Packages/AstraPersistence/Sources/Attachments.swift10// Module : Packages11// Repository : https://git.spboucher.ai/orix-astra12// Created : 2026-11-2113// Last Modified : 2026-11-2114//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author : Simon-Pierre Boucher20// Position : Professor of Finance21// Institution : Université du Québec en Outaouais (UQO)22// Department : Département des sciences administratives23// Organization : SP Boucher24//25// Website : https://spboucher.ai26// Git : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General : info@spboucher.ai33// Professional : contact@spboucher.ai34// Direct : simon@spboucher.ai35// Research : research@spboucher.ai36// Development : dev@spboucher.ai37// Support : support@spboucher.ai38// Security/Admin : admin@spboucher.ai39// Notifications : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification : Public66// Distribution : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License : Proprietary, all rights reserved (see license file)80// License File : LICENSE81// Maintainer : Simon-Pierre Boucher82// Technical Contact: dev@spboucher.ai83//84// =============================================================================85// END OF SP BOUCHER SOURCE HEADER86// =============================================================================8788import Foundation89import GRDB90import AstraCore9192/// Attachment bytes on disk: one file per distinct content, named by its SHA-256. A name supplied by a person or a model is93/// never part of a path, so there is nothing to traverse.94struct BlobDirectory: Sendable {95 let url: URL96 let maxBytes: Int9798 func prepare() throws {99 try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)100 AstraStore.protect(url)101 }102103 func fileURL(sha256: String) throws -> URL {104 guard Hashing.isSHA256(sha256) else { throw AstraStoreError.invalidAttachmentReference }105 return url.appendingPathComponent(sha256, isDirectory: false)106 }107108 /// Writes the bytes unless a file with the same content is already there. Returns the hash.109 func store(_ data: Data) throws -> String {110 guard data.count <= maxBytes else { throw AstraStoreError.attachmentTooLarge(limit: maxBytes, actual: data.count) }111 let hash = Hashing.sha256(data)112 let destination = try fileURL(sha256: hash)113 if !FileManager.default.fileExists(atPath: destination.path) {114 try prepare()115 #if os(macOS)116 try data.write(to: destination, options: [.atomic])117 #else118 try data.write(to: destination, options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication])119 #endif120 }121 return hash122 }123124 func data(sha256: String) throws -> Data {125 let source = try fileURL(sha256: sha256)126 guard FileManager.default.fileExists(atPath: source.path) else { throw AstraStoreError.missingAttachmentData(sha256) }127 return try Data(contentsOf: source, options: [.mappedIfSafe])128 }129130 /// Runs inside the write transaction: the database writer serializes it with orphan cleanup, so a file being attached can131 /// never be mistaken for an orphan.132 func attach(_ db: Database, _ draft: AttachmentDraft, messageID: String, at date: Date) throws -> AttachmentRecord {133 let hash = try store(draft.data)134 let record = AttachmentRecord(id: AstraID.new(), messageID: messageID, kind: draft.kind, filename: Self.displayName(draft.filename),135 mimeType: Self.cleanMIME(draft.mimeType), byteSize: draft.data.count, sha256: hash,136 extractedText: draft.extractedText, createdAt: date)137 try record.insert(db)138 return record139 }140141 /// The files this store wrote (names that are SHA-256 hashes). Anything else in the directory is not ours and is left alone.142 func files() -> [(name: String, bytes: Int64)] {143 let keys: [URLResourceKey] = [.fileSizeKey, .isRegularFileKey]144 let urls = (try? FileManager.default.contentsOfDirectory(at: url, includingPropertiesForKeys: keys)) ?? []145 return urls.compactMap { file in146 guard Hashing.isSHA256(file.lastPathComponent), let values = try? file.resourceValues(forKeys: Set(keys)),147 values.isRegularFile == true else { return nil }148 return (file.lastPathComponent, Int64(values.fileSize ?? 0))149 }.sorted { $0.name < $1.name }150 }151152 /// Removes every file no attachment row refers to. Returns the bytes freed.153 func removeOrphans(_ db: Database) throws -> Int64 {154 let referenced = Set(try String.fetchAll(db, sql: "SELECT DISTINCT sha256 FROM attachment"))155 var freed: Int64 = 0156 for file in files() where !referenced.contains(file.name) {157 if (try? FileManager.default.removeItem(at: url.appendingPathComponent(file.name))) != nil { freed += file.bytes }158 }159 return freed160 }161162 /// Last path component only, control characters and separators removed, bounded length.163 static func displayName(_ raw: String) -> String {164 let last = raw.replacingOccurrences(of: "\\", with: "/").split(separator: "/", omittingEmptySubsequences: true).last.map(String.init) ?? ""165 let scalars = last.unicodeScalars.filter { !CharacterSet.controlCharacters.contains($0) && $0 != "/" && $0 != ":" }166 var name = String(String.UnicodeScalarView(scalars)).trimmingCharacters(in: .whitespacesAndNewlines)167 while name.hasPrefix(".") { name.removeFirst() }168 if name.isEmpty { name = "attachment" }169 return String(name.prefix(200))170 }171172 static func cleanMIME(_ raw: String) -> String {173 let lower = raw.lowercased().trimmingCharacters(in: .whitespacesAndNewlines)174 let valid = lower.range(of: #"^[a-z0-9][a-z0-9!#$&^_.+\-]*/[a-z0-9][a-z0-9!#$&^_.+\-]*$"#, options: .regularExpression) != nil175 return valid ? lower : "application/octet-stream"176 }177}178179public extension AstraStore {180 /// Attaches a file to an existing message. Identical content is stored once, whatever its name.181 @discardableResult182 func addAttachment(messageID: String, _ draft: AttachmentDraft, at date: Date = Date()) async throws -> AttachmentRecord {183 let blobs = self.blobs184 return try await write { db in185 _ = try MessageRecord.require(db, messageID)186 return try blobs.attach(db, draft, messageID: messageID, at: date)187 }188 }189190 func attachments(messageID: String) async throws -> [AttachmentRecord] {191 try await read { db in try AttachmentRecord.filter(Column("messageID") == messageID).order(Column("createdAt"), Column("id")).fetchAll(db) }192 }193194 /// Attachments of every message of a conversation, keyed by message id.195 func attachments(conversationID: String) async throws -> [String: [AttachmentRecord]] {196 try await read { db in197 let all = try AttachmentRecord.fetchAll(db, sql: """198 SELECT a.* FROM attachment a JOIN message m ON m.id = a.messageID WHERE m.conversationID = ? ORDER BY a.createdAt, a.id199 """, arguments: [conversationID])200 return Dictionary(grouping: all, by: \.messageID)201 }202 }203204 func attachmentData(_ attachment: AttachmentRecord) async throws -> Data { try await attachmentData(sha256: attachment.sha256) }205206 func attachmentData(sha256: String) async throws -> Data { try blobs.data(sha256: sha256) }207208 /// Location of the stored file, for previews. Throws for anything that is not a SHA-256 this store produced.209 func attachmentFileURL(sha256: String) throws -> URL { try blobs.fileURL(sha256: sha256) }210211 /// Removes one attachment row; its file goes too when no other attachment has the same content.212 @discardableResult213 func deleteAttachment(id: String) async throws -> DeletionResult {214 let blobs = self.blobs215 return try await write { db in216 let removed = try AttachmentRecord.remove(db, id: id)217 return DeletionResult(rowsDeleted: removed ? 1 : 0, bytesFreed: try blobs.removeOrphans(db))218 }219 }220221 /// Deletes attachment files that no row refers to (left by a rolled-back write or a crash). Returns the bytes freed.222 @discardableResult223 func cleanupOrphanAttachments() async throws -> Int64 {224 let blobs = self.blobs225 return try await write { db in try blobs.removeOrphans(db) }226 }227228 /// Bytes used by attachment files on disk.229 func attachmentStorageBytes() async throws -> Int64 { blobs.files().reduce(0) { $0 + $1.bytes } }230231 func storageUsage() async throws -> StorageUsage {232 let files = blobs.files()233 let database = try await read { db in try Self.usedBytes(db) }234 return StorageUsage(databaseBytes: database, attachmentBytes: files.reduce(0) { $0 + $1.bytes }, attachmentFileCount: files.count)235 }236}237