Scarriffle/Calendarr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add 'CalendarrKit/' from commit '9ea1a8705d608b1aa476c0b35685c57466bb0c50'

Browse Source 
git-subtree-dir: CalendarrKit
git-subtree-mainline: 8bc32faa7f
git-subtree-split: 9ea1a8705d
This commit is contained in:
Scarriffle
2026-10-19 05:34:15 +02:00
parent 8bc32faa7f 9ea1a8705d
commit dccf8671b2
21 changed files with 1672 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CalendarrKit/Sources/CalendarrCore/AppGroup.swift
+31
View File
@@ -0,0 +1,31 @@
import Foundation
/// The App Group the Calendarr apps share.
///
/// The identifier registered in the Apple Developer portal never changes. What
/// changes is the string the *runtime* expects: macOS — including Mac Catalyst —
/// requires the Team ID prefix, and iOS forbids it.
///
/// Getting this wrong fails silently. `containerURL(forSecurityApplication‑
/// GroupIdentifier:)` returns nil, every read and write no-ops, and widgets show
/// placeholder content forever with no error raised anywhere. `current` must
/// therefore stay byte-identical to `com.apple.security.application-groups` in
/// the entitlements file used for the platform being built.
public enum CalendarrAppGroup {
/// As registered in the Apple Developer portal.
public static let unprefixed = "group.com.scarriffleservices.calendarr"
/// Team ID — the value `$(AppIdentifierPrefix)` expands to at build time.
public static let teamID = "PP34X97WS3"
/// The value to hand to `FileManager.containerURL(forSecurityApplicationGroupIdentifier:)`.
#if os(macOS) || targetEnvironment(macCatalyst)
public static let current = "\(teamID).\(unprefixed)"
#else
public static let current = unprefixed
#endif
/// Keychain access group shared across apps from this team. Requires
/// `keychain-access-groups` in the entitlements of every app that uses it.
public static let sharedKeychainGroup = "\(teamID).com.scarriffleservices.calendarr.shared"
}
CalendarrKit/Sources/CalendarrCore/CalendarKey.swift
+30
View File
@@ -0,0 +1,30 @@
import Foundation
/// Stable identifier for one calendar, used to tie a snapshot event back to the
/// calendar it came from.
///
/// This exists because the server reports `calendar_id` inconsistently: a raw
/// numeric for CalDAV sources, but `"<source>-<id>"` for local, iCal, Google and
/// Home Assistant (e.g. `"local-3"`). Any consumer that filters by calendar has
/// to normalise the two forms identically, or filtering silently does nothing
/// for the prefixed sources — which is exactly the bug this rule was written to
/// fix. Keeping the rule in one shared place is why it lives here rather than
/// being reimplemented per app.
public enum CalendarKey {
/// Build a key, stripping a redundant `"<source>-"` prefix from the id.
public static func make(source: String, calendarId: String) -> String {
var id = calendarId
let prefix = "\(source)-"
if id.hasPrefix(prefix) { id = String(id.dropFirst(prefix.count)) }
return "\(source):\(id)"
}
/// Split a key back into its source and numeric id.
/// Returns nil for malformed keys or non-numeric ids.
public static func parse(_ key: String) -> (source: String, id: Int)? {
guard let colon = key.firstIndex(of: ":") else { return nil }
let source = String(key[..<colon])
guard let id = Int(key[key.index(after: colon)...]) else { return nil }
return (source, id)
}
}
CalendarrKit/Sources/CalendarrCore/Complications/ComplicationTimeline.swift
+61
View File
@@ -0,0 +1,61 @@
import Foundation
/// When a complication needs to be redrawn.
///
/// A watch-face complication has a small refresh budget, so the timeline is
/// pre-computed from data the watch already holds instead of being refreshed on
/// a schedule: an entry on every event boundary means the complication changes
/// in the exact minute the next appointment does, without a network call.
public enum ComplicationTimeline {
/// Dates at which a complication should re-render.
///
/// Always begins with `now` so the first entry renders immediately. Event
/// starts and ends within `horizon` become entries.
///
/// The first `fineGrainedWindow` then gets a mark every minute, and the rest
/// of the horizon one every hour. The fine-grained part is what lets a
/// complication show a *compact* countdown — "23m" rather than "1:23:45" —
/// which is the only kind that fits an accessoryCorner or a circular gauge.
/// A live `Text(style: .timer)` needs no entries at all but is eight
/// characters wide, and overlaps the curved label it sits next to.
///
/// The result is sorted, deduplicated to the second, and capped at
/// `maxEntries`, keeping the earliest.
public static func entryDates(from now: Date,
in snapshot: CalendarrSnapshot,
horizon: TimeInterval = 24 * 3600,
fineGrainedWindow: TimeInterval = 3600,
maxEntries: Int = 150) -> [Date] {
let end = now.addingTimeInterval(horizon)
var seen: Set<Int> = []
var dates: [Date] = []
func add(_ date: Date) {
guard date >= now, date <= end else { return }
// Deduplicate to whole seconds: two events that meet exactly would
// otherwise produce two entries a float apart.
let key = Int(date.timeIntervalSince1970.rounded())
guard seen.insert(key).inserted else { return }
dates.append(date)
}
add(now)
for event in snapshot.events {
add(event.start)
add(event.end)
}
let fineEnd = min(end, now.addingTimeInterval(fineGrainedWindow))
var minute = now.addingTimeInterval(60)
while minute <= fineEnd {
add(minute)
minute = minute.addingTimeInterval(60)
}
var hourly = now.addingTimeInterval(3600)
while hourly <= end {
add(hourly)
hourly = hourly.addingTimeInterval(3600)
}
return Array(dates.sorted().prefix(maxEntries))
}
}
CalendarrKit/Sources/CalendarrCore/Session/SharedSession.swift
+85
View File
@@ -0,0 +1,85 @@
import Foundation
/// Non-secret session facts published alongside the snapshot.
///
/// This exists so a consumer can answer "which server, and is anyone signed in?"
/// without reading Calendarr's own `UserDefaults`, which lives in a different
/// sandbox. The auth token is deliberately *not* here — it belongs in the shared
/// keychain group, not in a plain file in the container.
public struct SharedSession: Codable, Sendable {
public static let currentSchema = 1
public static let maxSupportedSchema = 1
public let schemaVersion: Int
public let baseURL: String
public let username: String
public let isLoggedIn: Bool
public let writtenAt: Date
public init(baseURL: String, username: String, isLoggedIn: Bool, writtenAt: Date) {
self.schemaVersion = Self.currentSchema
self.baseURL = baseURL
self.username = username
self.isLoggedIn = isLoggedIn
self.writtenAt = writtenAt
}
public init(from decoder: Decoder) throws {
let c = try decoder.container(keyedBy: CodingKeys.self)
schemaVersion = try c.decodeIfPresent(Int.self, forKey: .schemaVersion) ?? 1
baseURL = try c.decode(String.self, forKey: .baseURL)
username = try c.decodeIfPresent(String.self, forKey: .username) ?? ""
isLoggedIn = try c.decodeIfPresent(Bool.self, forKey: .isLoggedIn) ?? true
writtenAt = try c.decodeIfPresent(Date.self, forKey: .writtenAt) ?? Date(timeIntervalSince1970: 0)
}
enum CodingKeys: String, CodingKey {
case schemaVersion, baseURL, username, isLoggedIn, writtenAt
}
/// The server URL as a `URL`, or nil when unset or malformed.
public var url: URL? { baseURL.isEmpty ? nil : URL(string: baseURL) }
}
public struct SharedSessionStore: Sendable {
private static let filename = "session.json"
public let appGroupID: String
public init(appGroupID: String = CalendarrAppGroup.current) {
self.appGroupID = appGroupID
}
private var fileURL: URL? {
FileManager.default
.containerURL(forSecurityApplicationGroupIdentifier: appGroupID)?
.appendingPathComponent(Self.filename)
}
/// Nil when Calendarr has never published, or the file is unreadable or newer
/// than this reader understands.
public func read() -> SharedSession? {
guard let url = fileURL, let data = try? Data(contentsOf: url) else { return nil }
let decoder = JSONDecoder()
decoder.dateDecodingStrategy = .iso8601
guard let session = try? decoder.decode(SharedSession.self, from: data),
session.schemaVersion <= SharedSession.maxSupportedSchema else { return nil }
return session
}
@_spi(Writer)
public func write(_ session: SharedSession) throws {
guard let url = fileURL else {
throw SnapshotStoreError.containerUnavailable(appGroupID: appGroupID)
}
let encoder = JSONEncoder()
encoder.dateEncodingStrategy = .iso8601
try encoder.encode(session).write(to: url, options: .atomic)
}
@_spi(Writer)
public func clear() {
guard let url = fileURL else { return }
try? FileManager.default.removeItem(at: url)
}
}
CalendarrKit/Sources/CalendarrCore/Snapshot/SnapshotChangeNotifier.swift
+62
View File
@@ -0,0 +1,62 @@
import Foundation
/// Cross-process "the snapshot changed" broadcast.
///
/// Two sandboxed apps cannot see each other's `NotificationCenter`, and neither
/// can poll the container cheaply. Darwin notifications are the one signal that
/// crosses the process boundary without an extra entitlement, a running
/// connection, or a shared framework.
///
/// The payload is always empty — Darwin notifications carry no data. The signal
/// means only "read again". If it is ever missed, a consumer that also reloads
/// on window activation degrades to a slightly stale view rather than a wrong one.
public enum SnapshotChangeNotifier {
public static let name = "com.scarriffleservices.calendarr.snapshot-changed"
/// Announce that the snapshot was rewritten. Called by `SnapshotStore`.
public static func post() {
CFNotificationCenterPostNotification(
CFNotificationCenterGetDarwinNotifyCenter(),
CFNotificationName(name as CFString),
nil, nil, true)
}
/// Start listening. The handler runs on an arbitrary thread, so hop to
/// whatever actor your UI needs before touching state.
///
/// Returns a token you must keep alive; deinit removes the observer.
public static func observe(_ handler: @escaping @Sendable () -> Void) -> ObservationToken {
ObservationToken(handler: handler)
}
public final class ObservationToken: @unchecked Sendable {
private let handler: @Sendable () -> Void
fileprivate init(handler: @escaping @Sendable () -> Void) {
self.handler = handler
// Darwin notifications hand back no context pointer we can rely on
// across process boundaries, so route through an unretained pointer
// to this token and look it up in the callback.
let observer = Unmanaged.passUnretained(self).toOpaque()
CFNotificationCenterAddObserver(
CFNotificationCenterGetDarwinNotifyCenter(),
observer,
{ _, observer, _, _, _ in
guard let observer else { return }
Unmanaged<ObservationToken>.fromOpaque(observer)
.takeUnretainedValue().handler()
},
SnapshotChangeNotifier.name as CFString,
nil,
.deliverImmediately)
}
deinit {
CFNotificationCenterRemoveObserver(
CFNotificationCenterGetDarwinNotifyCenter(),
Unmanaged.passUnretained(self).toOpaque(),
CFNotificationName(SnapshotChangeNotifier.name as CFString),
nil)
}
}
}
CalendarrKit/Sources/CalendarrCore/Snapshot/SnapshotFilter.swift
+32
View File
@@ -0,0 +1,32 @@
import Foundation
extension CalendarrSnapshot {
/// Keep only the listed calendars. An empty set means "every calendar",
/// which is what an unconfigured widget or complication asks for.
///
/// Filtering narrows the events but deliberately not the window: the
/// snapshot still speaks for the same range, it just has fewer calendars
/// in it.
public func filtered(toCalendarKeys keys: Set<String>) -> CalendarrSnapshot {
guard !keys.isEmpty else { return self }
return replacingEvents(events.filter { keys.contains($0.calendarKey) })
}
/// Remove the listed calendars, keeping everything else. An empty set is a
/// no-op.
public func filtered(excludingCalendarKeys keys: Set<String>) -> CalendarrSnapshot {
guard !keys.isEmpty else { return self }
return replacingEvents(events.filter { !keys.contains($0.calendarKey) })
}
private func replacingEvents(_ events: [SnapshotEvent]) -> CalendarrSnapshot {
CalendarrSnapshot(writtenAt: writtenAt,
coverageStart: coverageStart,
coverageEnd: coverageEnd,
isLoggedIn: isLoggedIn,
writerVersion: writerVersion,
events: events,
theme: theme,
language: language)
}
}
CalendarrKit/Sources/CalendarrCore/Snapshot/SnapshotModels.swift
+223
View File
@@ -0,0 +1,223 @@
import Foundation
// MARK: - Coverage policy
/// How much of the calendar the writer publishes. Shared so the writer and the
/// v1-file reconstruction below can never disagree about it.
public enum SnapshotCoverage {
/// Days before today. The current week must stay complete for widgets that
/// render Monday–today.
public static let daysBehind = 7
/// Days after today.
public static let daysAhead = 42
/// Hard cap on events written, applied after sorting by start date.
public static let maxEvents = 500
}
// MARK: - Event
/// One event as published to the shared container.
///
/// Deliberately lossy: notes, URL, source, creator, privacy, read-only status,
/// reminders and recurrence rules are all dropped. This is enough to *display* a
/// calendar and deliberately not enough to edit one or reason about permissions.
public struct SnapshotEvent: Codable, Sendable, Identifiable, Hashable {
public let id: String
public let title: String
public let start: Date
public let end: Date
public let isAllDay: Bool
public let colorHex: String
public let location: String
/// Ties the event to a calendar. See `CalendarKey`.
public let calendarKey: String
public init(id: String, title: String, start: Date, end: Date,
isAllDay: Bool, colorHex: String, location: String, calendarKey: String) {
self.id = id; self.title = title; self.start = start; self.end = end
self.isAllDay = isAllDay; self.colorHex = colorHex
self.location = location; self.calendarKey = calendarKey
}
// Lenient: caches written before calendarKey existed simply lack the field.
public init(from decoder: Decoder) throws {
let c = try decoder.container(keyedBy: CodingKeys.self)
id = try c.decode(String.self, forKey: .id)
title = try c.decode(String.self, forKey: .title)
start = try c.decode(Date.self, forKey: .start)
end = try c.decode(Date.self, forKey: .end)
isAllDay = try c.decode(Bool.self, forKey: .isAllDay)
colorHex = try c.decode(String.self, forKey: .colorHex)
location = try c.decode(String.self, forKey: .location)
calendarKey = try c.decodeIfPresent(String.self, forKey: .calendarKey) ?? ""
}
}
// MARK: - Calendar
/// A calendar available for filtering, published alongside the events so a
/// consumer can build a picker without a network call.
public struct SnapshotCalendar: Codable, Sendable, Identifiable, Hashable {
/// A `CalendarKey`, matching `SnapshotEvent.calendarKey`.
public let id: String
public let name: String
public let colorHex: String
public init(id: String, name: String, colorHex: String) {
self.id = id; self.name = name; self.colorHex = colorHex
}
}
// MARK: - Theme
/// The colours the app is currently rendering with, so a consumer can match it
/// without reading the app's own preferences.
public struct SnapshotTheme: Sendable, Hashable {
public let today: String
public let text: String
public let background: String
public let line: String
public let primary: String
public let accent: String
public init(today: String, text: String, background: String,
line: String, primary: String, accent: String) {
self.today = today; self.text = text; self.background = background
self.line = line; self.primary = primary; self.accent = accent
}
}
// MARK: - Snapshot
/// The published calendar snapshot.
///
/// ## Wire compatibility
///
/// The six colour values are stored **flat** at the top level rather than nested
/// under `theme`, even though `theme` is the nicer thing to read in code. That is
/// deliberate: v1 files carry them flat and a v1 reader requires them flat, so
/// nesting would break older readers on the very first v2 write. Within a major
/// version this format only ever gains optional fields — old readers ignore what
/// they do not know, new readers default what is missing. `theme` is a computed
/// view over the stored values, so callers get the clean shape anyway.
public struct CalendarrSnapshot: Codable, Sendable {
/// Bump only for a breaking change, and see the rules in the README.
public static let currentSchema = 2
/// Files claiming a higher schema are refused rather than mis-decoded.
public static let maxSupportedSchema = 2
public let schemaVersion: Int
public let writtenAt: Date
/// Start of the published window. Outside `coverageStart..<coverageEnd` the
/// snapshot carries *no information* — which is not the same as "no events".
public let coverageStart: Date
public let coverageEnd: Date
/// False once the user signs out. Distinguishes "signed out" from "never ran".
public let isLoggedIn: Bool
/// CFBundleShortVersionString of whoever wrote the file. Diagnostics only.
public let writerVersion: String
public let events: [SnapshotEvent]
public let language: String
// Stored flat for wire compatibility — read them via `theme`.
let todayColorHex: String
let textColorHex: String
let backgroundColorHex: String
let lineColorHex: String
let primaryColorHex: String
let accentColorHex: String
public var theme: SnapshotTheme {
SnapshotTheme(today: todayColorHex, text: textColorHex,
background: backgroundColorHex, line: lineColorHex,
primary: primaryColorHex, accent: accentColorHex)
}
/// True when `date` falls inside the published window, i.e. when an absence
/// of events for that date genuinely means "nothing scheduled".
public func covers(_ date: Date) -> Bool {
date >= coverageStart && date < coverageEnd
}
public init(writtenAt: Date,
coverageStart: Date,
coverageEnd: Date,
isLoggedIn: Bool,
writerVersion: String,
events: [SnapshotEvent],
theme: SnapshotTheme,
language: String) {
self.schemaVersion = Self.currentSchema
self.writtenAt = writtenAt
self.coverageStart = coverageStart
self.coverageEnd = coverageEnd
self.isLoggedIn = isLoggedIn
self.writerVersion = writerVersion
self.events = events
self.language = language
self.todayColorHex = theme.today
self.textColorHex = theme.text
self.backgroundColorHex = theme.background
self.lineColorHex = theme.line
self.primaryColorHex = theme.primary
self.accentColorHex = theme.accent
}
/// Lenient decoder. Everything added after v1 is optional here, and a v1
/// file's coverage window is reconstructed from the policy that produced it.
public init(from decoder: Decoder) throws {
let c = try decoder.container(keyedBy: CodingKeys.self)
schemaVersion = try c.decodeIfPresent(Int.self, forKey: .schemaVersion) ?? 1
writtenAt = try c.decode(Date.self, forKey: .writtenAt)
events = try c.decode([SnapshotEvent].self, forKey: .events)
language = try c.decode(String.self, forKey: .language)
todayColorHex = try c.decode(String.self, forKey: .todayColorHex)
textColorHex = try c.decode(String.self, forKey: .textColorHex)
backgroundColorHex = try c.decode(String.self, forKey: .backgroundColorHex)
lineColorHex = try c.decode(String.self, forKey: .lineColorHex)
primaryColorHex = try c.decodeIfPresent(String.self, forKey: .primaryColorHex) ?? "#4285f4"
accentColorHex = try c.decodeIfPresent(String.self, forKey: .accentColorHex) ?? "#ea4335"
isLoggedIn = try c.decodeIfPresent(Bool.self, forKey: .isLoggedIn) ?? true
writerVersion = try c.decodeIfPresent(String.self, forKey: .writerVersion) ?? "unknown"
// v1 had no explicit window; it always wrote the same one, measured from
// the start of the day it was written.
let cal = Calendar(identifier: .gregorian)
let dayStart = cal.startOfDay(for: writtenAt)
coverageStart = try c.decodeIfPresent(Date.self, forKey: .coverageStart)
?? cal.date(byAdding: .day, value: -SnapshotCoverage.daysBehind, to: dayStart) ?? dayStart
coverageEnd = try c.decodeIfPresent(Date.self, forKey: .coverageEnd)
?? cal.date(byAdding: .day, value: SnapshotCoverage.daysAhead, to: dayStart) ?? dayStart
}
enum CodingKeys: String, CodingKey {
case schemaVersion, writtenAt, coverageStart, coverageEnd, isLoggedIn, writerVersion
case events, language
case todayColorHex, textColorHex, backgroundColorHex, lineColorHex
case primaryColorHex, accentColorHex
}
}
// MARK: - Read result
/// Why a read produced no usable snapshot. The distinction matters for the UI:
/// "never ran", "signed out" and "genuinely empty" call for different messages.
public enum SnapshotReadResult: Sendable {
case ok(CalendarrSnapshot)
/// The user signed out of Calendarr. Show a sign-in prompt, not stale events.
case loggedOut(writtenAt: Date)
/// Calendarr has never published on this machine. Ask the user to open it once.
case neverWritten
/// Written by a newer Calendarr than this reader understands. Refuse rather
/// than guess; ask the user to update.
case incompatible(foundSchema: Int, maxSupported: Int)
/// Corrupt file, or — much more likely — a misconfigured App Group.
case unreadable(String)
public var snapshot: CalendarrSnapshot? {
if case .ok(let s) = self { return s }
return nil
}
}
CalendarrKit/Sources/CalendarrCore/Snapshot/SnapshotStore.swift
+139
View File
@@ -0,0 +1,139 @@
import Foundation
public enum SnapshotStoreError: Error, LocalizedError {
case containerUnavailable(appGroupID: String)
public var errorDescription: String? {
switch self {
case .containerUnavailable(let id):
return "App Group container unavailable for \(id). Check that "
+ "com.apple.security.application-groups in this target's "
+ "entitlements matches exactly, and that macOS builds use the "
+ "Team ID prefix."
}
}
}
/// Reads — and, for Calendarr itself, writes — the shared calendar snapshot.
///
/// Writing is gated behind `@_spi(Writer)` so a read-only consumer cannot
/// corrupt the shared cache even by accident. Calendarr imports the package as
/// `@_spi(Writer) import CalendarrCore`; everyone else gets read access only.
public struct SnapshotStore: Sendable {
private static let cacheFilename = "widget-cache.json"
private static let calendarsFilename = "widget-calendars.json"
public let appGroupID: String
public init(appGroupID: String = CalendarrAppGroup.current) {
self.appGroupID = appGroupID
}
private var containerURL: URL? {
FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: appGroupID)
}
private static func encoder() -> JSONEncoder {
let e = JSONEncoder()
e.dateEncodingStrategy = .iso8601
return e
}
private static func decoder() -> JSONDecoder {
let d = JSONDecoder()
d.dateDecodingStrategy = .iso8601
return d
}
// MARK: - Reading
/// Load the published snapshot.
///
/// Never returns a bare nil: every failure mode is named, because they call
/// for different things in the UI and because a silent nil is precisely how
/// a misconfigured App Group used to hide itself.
public func read() -> SnapshotReadResult {
guard let container = containerURL else {
return .unreadable(SnapshotStoreError
.containerUnavailable(appGroupID: appGroupID).localizedDescription)
}
let url = container.appendingPathComponent(Self.cacheFilename)
guard FileManager.default.fileExists(atPath: url.path) else {
// No cache. Signing out deletes the events — keeping them would leak
// the previous user's calendar — so the session file is what tells
// "signed out" apart from "never ran here". Answering that in one
// call keeps every consumer from reimplementing the distinction.
if let session = SharedSessionStore(appGroupID: appGroupID).read(),
!session.isLoggedIn {
return .loggedOut(writtenAt: session.writtenAt)
}
return .neverWritten
}
let data: Data
do { data = try Data(contentsOf: url) }
catch { return .unreadable("Could not read \(Self.cacheFilename): \(error.localizedDescription)") }
// Check the version before decoding: a newer writer may have changed the
// meaning of a field we think we understand, so refusing beats guessing.
if let probe = try? Self.decoder().decode(SchemaProbe.self, from: data) {
let found = probe.schemaVersion ?? 1
if found > CalendarrSnapshot.maxSupportedSchema {
return .incompatible(foundSchema: found,
maxSupported: CalendarrSnapshot.maxSupportedSchema)
}
}
do {
let snapshot = try Self.decoder().decode(CalendarrSnapshot.self, from: data)
guard snapshot.isLoggedIn else { return .loggedOut(writtenAt: snapshot.writtenAt) }
return .ok(snapshot)
} catch {
return .unreadable("Could not decode \(Self.cacheFilename): \(error)")
}
}
/// The calendars available for filtering. Empty when nothing is published.
public func readCalendars() -> [SnapshotCalendar] {
guard let url = containerURL?.appendingPathComponent(Self.calendarsFilename),
let data = try? Data(contentsOf: url) else { return [] }
return (try? Self.decoder().decode([SnapshotCalendar].self, from: data)) ?? []
}
/// Reads only the version field, so an unsupported file is never fully decoded.
private struct SchemaProbe: Decodable { let schemaVersion: Int? }
// MARK: - Writing (Calendarr only)
@_spi(Writer)
public func write(_ snapshot: CalendarrSnapshot) throws {
guard let container = containerURL else {
throw SnapshotStoreError.containerUnavailable(appGroupID: appGroupID)
}
let data = try Self.encoder().encode(snapshot)
try data.write(to: container.appendingPathComponent(Self.cacheFilename), options: .atomic)
SnapshotChangeNotifier.post()
}
@_spi(Writer)
public func writeCalendars(_ calendars: [SnapshotCalendar]) throws {
guard let container = containerURL else {
throw SnapshotStoreError.containerUnavailable(appGroupID: appGroupID)
}
let data = try Self.encoder().encode(calendars)
try data.write(to: container.appendingPathComponent(Self.calendarsFilename), options: .atomic)
}
/// Remove everything published. Call this on sign-out and on server reset —
/// the container outlives the session, so without it the next reader keeps
/// rendering the previous user's calendar.
@_spi(Writer)
public func clear() {
guard let container = containerURL else { return }
for name in [Self.cacheFilename, Self.calendarsFilename] {
try? FileManager.default.removeItem(at: container.appendingPathComponent(name))
}
SnapshotChangeNotifier.post()
}
}
CalendarrKit/Sources/CalendarrCore/Snapshot/WatchCoverage.swift
+67
View File
@@ -0,0 +1,67 @@
import Foundation
/// How much of the calendar travels to the watch.
///
/// Deliberately narrower than `SnapshotCoverage`: the payload crosses
/// WatchConnectivity on every publish, and a watch complication never needs six
/// weeks of history to answer "what is next".
public enum WatchCoverage {
/// Days before today. One is enough for "still running" all-day events.
public static let daysBehind = 1
/// Days after today.
public static let daysAhead = 14
/// Hard cap on events sent, applied after sorting by start date.
public static let maxEvents = 120
}
extension CalendarrSnapshot {
/// A narrower copy of this snapshot, suitable for sending to the watch.
///
/// The coverage window shrinks together with the events, and never widens
/// past what the writer already claimed. If `WatchCoverage.maxEvents`
/// truncates the list, `coverageEnd` is pulled back to the first event we
/// had to drop: everything before that point is provably complete, and
/// beyond it the watch must not pretend to know anything.
public func trimmedForWatch(now: Date = Date(),
calendar: Calendar = Calendar(identifier: .gregorian)) -> CalendarrSnapshot {
let dayStart = calendar.startOfDay(for: now)
let windowStart = max(coverageStart,
calendar.date(byAdding: .day, value: -WatchCoverage.daysBehind, to: dayStart) ?? dayStart)
let windowEnd = min(coverageEnd,
calendar.date(byAdding: .day, value: WatchCoverage.daysAhead, to: dayStart) ?? dayStart)
guard windowEnd > windowStart else {
return Self.rebuilt(from: self, start: windowStart, end: windowStart, events: [])
}
let inWindow = events
.filter { $0.start < windowEnd && $0.end > windowStart }
.sorted { $0.start < $1.start }
guard inWindow.count > WatchCoverage.maxEvents else {
return Self.rebuilt(from: self, start: windowStart, end: windowEnd, events: inWindow)
}
let kept = Array(inWindow.prefix(WatchCoverage.maxEvents))
// The first dropped event marks the edge of what we can prove. Its start
// becomes the new end of coverage; the last kept event is dropped too
// when it starts at that same instant, which keeps the invariant
// "every event we carry starts before coverageEnd" exactly true.
let provenEnd = max(windowStart, min(windowEnd, inWindow[WatchCoverage.maxEvents].start))
return Self.rebuilt(from: self, start: windowStart, end: provenEnd,
events: kept.filter { $0.start < provenEnd && $0.end > windowStart })
}
private static func rebuilt(from source: CalendarrSnapshot,
start: Date, end: Date,
events: [SnapshotEvent]) -> CalendarrSnapshot {
CalendarrSnapshot(writtenAt: source.writtenAt,
coverageStart: start,
coverageEnd: end,
isLoggedIn: source.isLoggedIn,
writerVersion: source.writerVersion,
events: events,
theme: source.theme,
language: source.language)
}
}
CalendarrKit/Sources/CalendarrCore/Transport/WatchPushPolicy.swift
+35
View File
@@ -0,0 +1,35 @@
import Foundation
/// Identifies the appointment a complication is currently showing.
///
/// The start date is part of the identity on purpose: a moved event keeps its
/// id, and the complication is wrong until it is told.
public struct NextEventIdentity: Equatable, Sendable, Codable {
public let id: String
public let start: Date
public init(id: String, start: Date) {
self.id = id
self.start = start
}
}
public enum WatchPushPolicy {
/// The first event that has not ended yet — which is what every "next
/// appointment" complication renders, including one that is running now.
public static func nextEventIdentity(in snapshot: CalendarrSnapshot,
at now: Date) -> NextEventIdentity? {
snapshot.events
.filter { $0.end > now }
.min { $0.start < $1.start }
.map { NextEventIdentity(id: $0.id, start: $0.start) }
}
/// Whether this change is worth one of the day's limited complication
/// pushes. Only a changed next appointment is — everything else reaches the
/// watch on the next application-context delivery.
public static func shouldPushComplicationUpdate(previous: NextEventIdentity?,
current: NextEventIdentity?) -> Bool {
previous != current
}
}
CalendarrKit/Sources/CalendarrCore/Transport/WatchTransportPayload.swift
+101
View File
@@ -0,0 +1,101 @@
import Foundation
/// Dictionary keys used on the WatchConnectivity wire. Stable within a major
/// version, like the snapshot filenames.
public enum WatchTransportKey {
public static let schema = "schema"
public static let snapshot = "snapshot"
public static let calendars = "calendars"
public static let session = "session"
}
public enum WatchTransportError: Error, Equatable, LocalizedError {
case missingSnapshot
case unsupportedSchema(found: Int, maxSupported: Int)
case malformed(String)
public var errorDescription: String? {
switch self {
case .missingSnapshot:
return "Watch payload carried no snapshot."
case .unsupportedSchema(let found, let max):
return "Watch payload schema \(found) is newer than this build understands (\(max))."
case .malformed(let why):
return "Watch payload could not be decoded: \(why)"
}
}
}
/// What the phone sends to the watch: a trimmed snapshot, the calendar list for
/// a filter UI, and the non-secret session facts so the watch can tell "signed
/// out" from "never received anything".
///
/// The auth token is deliberately absent. The watch never talks to the server,
/// so there is nothing for it to authenticate with and nothing to leak.
public struct WatchTransportPayload: Sendable {
/// Bump only for a breaking change to the dictionary shape.
public static let currentSchema = 1
/// Payloads claiming a higher schema are refused rather than mis-decoded.
public static let maxSupportedSchema = 1
public let snapshot: CalendarrSnapshot
public let calendars: [SnapshotCalendar]
public let session: SharedSession?
public init(snapshot: CalendarrSnapshot,
calendars: [SnapshotCalendar],
session: SharedSession?) {
self.snapshot = snapshot
self.calendars = calendars
self.session = session
}
private static func encoder() -> JSONEncoder {
let e = JSONEncoder(); e.dateEncodingStrategy = .iso8601; return e
}
private static func decoder() -> JSONDecoder {
let d = JSONDecoder(); d.dateDecodingStrategy = .iso8601; return d
}
/// Encode for `WCSession`. Values are `Data` and `Int` only, because
/// WatchConnectivity accepts property-list types and rejects everything
/// else at runtime rather than at compile time.
public func encoded() throws -> [String: Any] {
let e = Self.encoder()
var dict: [String: Any] = [
WatchTransportKey.schema: Self.currentSchema,
WatchTransportKey.snapshot: try e.encode(snapshot),
WatchTransportKey.calendars: try e.encode(calendars),
]
if let session { dict[WatchTransportKey.session] = try e.encode(session) }
return dict
}
public static func decode(_ dict: [String: Any]) throws -> WatchTransportPayload {
let found = dict[WatchTransportKey.schema] as? Int ?? 1
guard found <= maxSupportedSchema else {
throw WatchTransportError.unsupportedSchema(found: found, maxSupported: maxSupportedSchema)
}
guard let snapshotData = dict[WatchTransportKey.snapshot] as? Data else {
throw WatchTransportError.missingSnapshot
}
let d = decoder()
let snapshot: CalendarrSnapshot
do { snapshot = try d.decode(CalendarrSnapshot.self, from: snapshotData) }
catch { throw WatchTransportError.malformed("snapshot: \(error)") }
var calendars: [SnapshotCalendar] = []
if let data = dict[WatchTransportKey.calendars] as? Data {
calendars = (try? d.decode([SnapshotCalendar].self, from: data)) ?? []
}
var session: SharedSession?
if let data = dict[WatchTransportKey.session] as? Data {
session = try? d.decode(SharedSession.self, from: data)
}
return WatchTransportPayload(snapshot: snapshot, calendars: calendars, session: session)
}
}