diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0cbced4..a98138c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -53,37 +53,6 @@ jobs: with: severity: warning - extensions: - name: validate + test extensions - runs-on: ubuntu-latest - steps: - # Full history: the version check resolves a merge base, which the - # default shallow clone does not contain. - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - fetch-depth: 0 - - # Curation is the security model for extensions, and a reviewer reads a - # diff — which does not show where a symlink points. This is the part of - # the review a human cannot reliably do by eye. - - name: validate - run: ./scripts/package-extensions.sh validate - - # The same script `make test-extensions` runs, so the gate and the local - # loop cannot drift. - - name: test extensions - run: ./scripts/test-extensions.sh - - # A changed extension that keeps its version is published as an update - # nobody can get: the app compares version strings to decide one exists, - # so republishing under the old number reaches no one who already - # installed it. - - name: check extension versions - if: github.event_name == 'pull_request' - run: | - git fetch --no-tags origin "${{ github.base_ref }}" - ./scripts/check-extension-versions.sh "origin/${{ github.base_ref }}" - build-macos: name: swift build (${{ matrix.arch }}) runs-on: macos-15 diff --git a/.gitignore b/.gitignore index ce4d5b7..f71f514 100644 --- a/.gitignore +++ b/.gitignore @@ -27,10 +27,3 @@ venv/ /tmp/ *.log keys/ -# The Pylon extension's cache, written beside it when run from a checkout. It -# holds customer account names, issue links and message previews. -extensions/pylon/state.json* -# Extensions that compile themselves on first run (away) build into .build/ -# beside their source. Already covered by .build/ above; named here so it -# survives anyone narrowing that line to the root. -extensions/*/.build/ diff --git a/Makefile b/Makefile index 6d011af..6693769 100644 --- a/Makefile +++ b/Makefile @@ -79,13 +79,6 @@ typecheck-tests: test-without-xcode: @./scripts/run-tests-without-xcode.sh $(NAME) -# The reference extensions' own tests, the same way CI runs them. They are -# Python rather than XCTest because the extensions are — nothing in an -# extension is Swift, and a script's tests belong beside the script. -.PHONY: test-extensions -test-extensions: - @./scripts/test-extensions.sh - # One-shot dev cycle: rebuild, reinstall the app, refresh notify.sh in # ~/.stack-nudge so hook-side changes propagate, kickstart the daemon. # Build output goes to $(BUILD_LOG); on failure, last 20 lines tail to stderr. diff --git a/Package.swift b/Package.swift index b08d68a..b202184 100644 --- a/Package.swift +++ b/Package.swift @@ -47,7 +47,6 @@ let package = Package( "phrases", "hooks", "docs", - "extensions", // Tests own this directory; declare here so SPM doesn't // sweep the test sources into the library target. diff --git a/Tests/StackNudgePanelCoreTests/AwayPresenceTests.swift b/Tests/StackNudgePanelCoreTests/AwayPresenceTests.swift index f829a4b..026e7c0 100644 --- a/Tests/StackNudgePanelCoreTests/AwayPresenceTests.swift +++ b/Tests/StackNudgePanelCoreTests/AwayPresenceTests.swift @@ -4,7 +4,8 @@ import XCTest // The app's half of Away: what the presence signal makes it do, and the // Settings row that decides whether leaving locks the screen. The detection -// itself is extensions/away, tested by its own suite. +// itself is the away extension, tested by its own suite in the extensions +// marketplace. final class AwayPresenceTests: XCTestCase { func testAwayLocksOnlyWhenTheSettingSaysTo() { diff --git a/docs/extensions.md b/docs/extensions.md index c0bc3ab..e667d20 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -380,8 +380,8 @@ these?" is a question the reference should answer. Any `extensions/*/test_*.py` is run by CI and by `pnpm check` there; a suite that discovers zero tests is a failure rather than a pass. -`scripts/package-extensions.sh validate` is what CI runs, and you can run it -yourself. It refuses: +`scripts/package-extensions.sh validate`, in the marketplace and in every catalogue made from +the template, is what CI runs, and you can run it yourself. It refuses: - a manifest that doesn't parse, or whose `id` disagrees with the directory name - an `id` outside `^[a-z0-9][a-z0-9-]{0,31}$`, or a `schema` that isn't 1 or 2 @@ -434,8 +434,10 @@ those hosts can't read any catalogue without it. A team can publish its own extensions from another repository, a private one included, and have them show up in the browser next to these. The repository -publishes exactly what this one does: run `scripts/package-extensions.sh` and -attach the index, the packages and their sidecars to its latest release. Then +publishes exactly what the marketplace does, and the simplest way is to make it +from [StackOneHQ/stack-nudge-extensions-template](https://github.com/StackOneHQ/stack-nudge-extensions-template), +whose release workflow attaches the index, the packages and their sidecars to +its latest release. Then each person who wants it adds the repository under **Settings → Extensions → Other catalogues**, which writes it to `~/.stack-nudge/config`: @@ -479,7 +481,7 @@ hardware capabilities such as `bluetooth`. The full table is in the design note, under "Privilege tiers". The tier is the reviewers' call, not the extension's, so it lives outside the -package, in `extensions/tiers.json`: +package, in the catalogue's `extensions/tiers.json`: ```json { "away": "trusted" } @@ -586,7 +588,7 @@ empty list, is refused. ## Away, the reference service extension -`extensions/away` notices when you walk away from the Mac with your phone, and +`extensions/away` in StackOneHQ/stack-nudge-extensions-marketplace notices when you walk away from the Mac with your phone, and sets the app's `presence` signal. It is the one to read when writing a service: - **`manifest.json`** asks for `bluetooth` and `signal:presence`, both diff --git a/docs/setup.md b/docs/setup.md index c47cce1..efcba46 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -99,7 +99,6 @@ make dev # watch sources; auto-reload on .swift / Info.plist / n make test # swift test (needs full Xcode for XCTest) make test-without-xcode # compile and run the tests with the Command Line Tools only make test-notify # drive notify.sh against a fake panel socket (macOS, no Xcode) -make test-extensions # validate and test the bundled extensions make uninstall # remove app, hooks, launchd agents, ~/.stack-nudge/ ``` @@ -115,7 +114,6 @@ Source layout: - `hook-manifest.json` — which agent events get wired to `notify.sh` - `hooks/` — the Claude Code plugin hooks and the pi extension - `phrases/` — per-language voice phrase pools sourced by `notify.sh` at hook time -- `extensions/` — the extensions in the catalogue; see [extensions.md](extensions.md) - `shared/` — code shared with the Linux/Windows surfaces - `scripts/`, `Tests/` — release and packaging scripts, and the test suite diff --git a/extensions/away/away.swift b/extensions/away/away.swift deleted file mode 100644 index cd0ba22..0000000 --- a/extensions/away/away.swift +++ /dev/null @@ -1,1069 +0,0 @@ -// Away: tells StackNudge when you've walked away from the Mac with your phone. -// -// A service extension (docs/design/service-extensions.md). It runs for as long -// as it's enabled, speaks the line protocol on stdin and stdout, and sets the -// app's `presence` signal to "away" or "present". It never locks the screen -// itself: the app does that when the signal changes, if the user asked for it, -// so turning locking off is an app setting and a crashed extension can't leave -// anything locked. -// -// How it decides. A paired phone advertises over Bluetooth LE under an -// identifier macOS keeps stable through the pairing, whether or not its screen -// is on, so a passive scan hears it without connecting to anything or -// installing anything on the phone. You count as away once the Mac has been -// idle for the configured time AND the phone hasn't been heard for the -// configured silence (two minutes unless set). Signal strength can't tell -// leaving from lying still: measured on a Galaxy S25+, an idle phone on the -// desk went 75 s between advertisements with readings as low as -99 dBm, no -// stronger than the last readings while walking out. So only a long silence -// counts. -// -// Built by ./run with `swiftc -O` on first start, so what a reviewer reads is -// what runs. stdout carries protocol lines and nothing else; anything for a -// human goes to stderr, which the host discards. - -import AppKit -import CoreBluetooth -import CoreGraphics -import Foundation -import IOBluetooth - -// MARK: - The rule - -enum PresenceState: Equatable { - case present - case away -} - -// The decision, as a value with no Bluetooth in it, so `--self-test` can drive -// it with timestamps. Away takes the phone being silent *and* the Mac being -// idle, so the screen never locks under someone who's typing. -struct PresenceTracker { - struct Rule: Equatable { - // No advertisement for this long means the phone is out of range. - var missingAfter: TimeInterval = TimeInterval(AwayConfig.defaultSilence) - // And nobody has touched the Mac for this long. - var idleAtLeast: TimeInterval = TimeInterval(AwayConfig.defaultIdle) - // A reading at least this strong brings you back. - var backRSSI: Int = -80 - - // The two config keys, independent of each other. The silence is - // floored by AwayConfig at 90 s: an idle phone on the desk was measured - // going 75 s without advertising, and a 20 s floor in the prototype - // locked the screen under the user dozens of times a day. - init(idle: TimeInterval, silence: TimeInterval) { - idleAtLeast = idle - missingAfter = silence - } - - init() {} - } - - var rule = Rule() - private(set) var state: PresenceState = .present - private(set) var lastSeen: Date? - - init(rule: Rule = Rule()) { self.rule = rule } - - // One advertisement from the phone. - mutating func observe(rssi: Int, at now: Date) { - // CoreBluetooth reports 127 when it has no reading. - guard rssi < 0 else { return } - lastSeen = now - if state == .away && rssi >= rule.backRSSI { state = .present } - } - - // A stretch in which silence says nothing about where the phone is: the - // Mac asleep, or Bluetooth off. Away then needs the phone heard afresh, - // rather than counting the gap as the phone having gone. - mutating func forgetHeard() { - lastSeen = nil - } - - // The phone was heard at `lastSeen` by a sighting this tracker wasn't - // given. Silence counts from the later of the two. Unless nothing counts - // yet: after a sleep, or Bluetooth coming back, the phone has to be heard - // afresh, and that sighting may be from before the gap. - mutating func catchUp(lastSeen heard: Date) { - guard let lastSeen, heard > lastSeen else { return } - self.lastSeen = heard - } - - // Called on a timer. Input on the Mac always means you're there. - @discardableResult - mutating func evaluate(now: Date, idle: TimeInterval) -> PresenceState { - if idle < rule.idleAtLeast { - state = .present - return state - } - guard state == .present else { return state } - if let lastSeen, now.timeIntervalSince(lastSeen) >= rule.missingAfter { - state = .away - // After input brings you back, away needs the phone heard afresh. - // Otherwise a phone left at home or switched off would lock the - // screen after every pause. - self.lastSeen = nil - } - return state - } -} - -// Notices that the Mac slept, from the clock jumping between ticks. A timer -// doesn't fire while the Mac is asleep, so the first tick after waking comes -// long after the one before. NSWorkspace's sleep notifications say the same -// thing when they reach this process; this is the check that doesn't depend -// on them. -struct SleepGap { - // Ticks are a second apart; ten seconds between two is not a busy run loop. - static let threshold: TimeInterval = 10 - private var lastTick: Date? - - mutating func slept(tickAt now: Date) -> Bool { - defer { lastTick = now } - guard let lastTick else { return false } - return now.timeIntervalSince(lastTick) > Self.threshold - } -} - -// MARK: - Names - -// Phone names are typed by people and printed by phones, so they're compared -// loosely: a curly apostrophe (what iOS and Android put in "Alex’s iPhone") -// matches a straight one, case doesn't matter, and surrounding space is -// ignored. Used for the configured name and the paired names alike. -enum PhoneName { - static func normalised(_ name: String) -> String { - name.replacingOccurrences(of: "\u{2019}", with: "'") - .replacingOccurrences(of: "\u{2018}", with: "'") - .trimmingCharacters(in: .whitespacesAndNewlines) - .lowercased() - } -} - -// MARK: - Which device is the phone - -// Decides which identifier is the phone, from the paired devices advertising -// the configured name. Pure, so the self-test can drive it. -// -// A name can be shared (two "iPhone"s, or a phone and a watch), and a phone -// might be bound to the wrong one of them. So when two identifiers with the -// name have both been heard within the silence window, it binds to neither, -// and Away never goes away until that's resolved. And when the bound one has -// gone silent for the whole window while exactly one other with the name is -// being heard, it moves to that one. -struct PhoneBinding { - enum Status: Equatable { - case notFound - case bound(UUID) - case ambiguous(count: Int) - } - - private(set) var bound: UUID? - private var heard: [UUID: Date] = [:] - - // An advertisement from a paired device carrying the configured name. - mutating func observe(_ id: UUID, at now: Date) { - heard[id] = now - } - - mutating func resolve(now: Date, window: TimeInterval) -> Status { - heard = heard.filter { now.timeIntervalSince($0.value) < window * 4 } - let recent = heard.filter { now.timeIntervalSince($0.value) < window }.map(\.key) - if recent.count > 1 { return .ambiguous(count: recent.count) } - if let only = recent.first, only != bound { - // Nothing bound yet, or the bound one has been silent for the whole - // window while this one is heard. - bound = only - } - return bound.map(Status.bound) ?? .notFound - } - - // `resolve`, keeping `tracker` up with the phone it's bound to. The - // tracker only hears the bound identifier while it's bound, so whenever - // the binding settles it can be behind: - // - The phone can start advertising under a new identifier while it's - // still in the room (a Galaxy S25+ did with Bluetooth switched off). - // Moving to it comes only after the old one has been silent for the - // whole window, so the tracker's sighting, the old one's, is already - // past `missingAfter`. - // - While another device with the name makes it ambiguous, the bound - // one's adverts aren't passed on, and ambiguity can end on the same - // identifier. - // Either way the next tick would lock with the phone on the desk, so the - // tracker catches up to the bound identifier's latest sighting. - mutating func resolve(now: Date, window: TimeInterval, - following tracker: inout PresenceTracker) -> Status { - let status = resolve(now: now, window: window) - if case .bound(let id) = status, let heard = heard[id] { - tracker.catchUp(lastSeen: heard) - } - return status - } -} - -// MARK: - Configuration - -struct AwayConfig: Equatable { - static let phoneKey = "STACKNUDGE_EXT_AWAY_PHONE" - static let idleKey = "STACKNUDGE_EXT_AWAY_IDLE" - static let silenceKey = "STACKNUDGE_EXT_AWAY_SILENCE" - static let defaultIdle = 30 - static let idleRange = 10...120 - static let defaultSilence = 120 - // Above the longest gap measured from an idle phone on a desk (75 s). - static let silenceRange = 90...600 - - // The phone's Bluetooth name, as Settings offers it. nil until set. - var phone: String? - var idleSeconds: Int = defaultIdle - var silenceSeconds: Int = defaultSilence - - // The host omits a key that isn't set, so a missing key and an empty one - // are the same thing here. A value that isn't a number falls back to the - // default rather than to a bound, since it says nothing about intent. - init(values: [String: String]) { - let phone = values[Self.phoneKey]?.trimmingCharacters(in: .whitespacesAndNewlines) - self.phone = (phone?.isEmpty ?? true) ? nil : phone - idleSeconds = Self.seconds(values[Self.idleKey], default: Self.defaultIdle, in: Self.idleRange) - silenceSeconds = Self.seconds(values[Self.silenceKey], default: Self.defaultSilence, - in: Self.silenceRange) - } - - var rule: PresenceTracker.Rule { - PresenceTracker.Rule(idle: TimeInterval(idleSeconds), silence: TimeInterval(silenceSeconds)) - } - - private static func seconds(_ raw: String?, default fallback: Int, in range: ClosedRange) -> Int { - guard let raw = raw?.trimmingCharacters(in: .whitespaces), let n = Int(raw) else { return fallback } - return min(max(n, range.lowerBound), range.upperBound) - } -} - -// MARK: - Output - -// One protocol line on stdout. Sorted keys so the same state prints the same -// bytes, which is what lets `publish` skip a document that hasn't changed. -enum Out { - // The host's ceiling for anything but a document is 64 KB; a document may - // be bigger, but this one never needs to be, so every line stays under it. - static let maxLineBytes = 64 * 1024 - - static func line(_ object: [String: Any]) -> Data? { - guard var data = try? JSONSerialization.data(withJSONObject: object, - options: [.sortedKeys, .withoutEscapingSlashes]) - else { return nil } - data.append(0x0A) - return data - } - - static func send(_ object: [String: Any]) { - guard let data = line(object), data.count < maxLineBytes else { - FileHandle.standardError.write(Data("away: dropped an oversized line\n".utf8)) - return - } - FileHandle.standardOutput.write(data) - } -} - -// MARK: - The tab - -// A device the scan has heard from. -struct Nearby: Equatable { - let id: UUID - let name: String - var rssi: Int - var lastSeen: Date -} - -// Everything the tab shows, gathered so the document can be built (and -// tested) without a scan. -struct Snapshot { - enum Phone: Equatable { - case notChosen - // The configured name isn't among the Mac's paired devices. - case notPaired - case notFound - case ambiguous(count: Int) - case bound - } - - var config: AwayConfig - var issue: String? - var scanning: Bool - var phone: Phone - var state: PresenceState - var rssi: Int? - var heard: Date? - var others: [Nearby] - var now: Date -} - -enum Tab { - // "4 s", "3 min", "2 h". Signals arrive seconds apart, so seconds are - // worth showing until they stop being readable. - static func duration(_ seconds: Int) -> String { - if seconds < 60 { return "\(seconds) s" } - if seconds < 3600 { return "\(seconds / 60) min" } - return "\(seconds / 3600) h" - } - - // A real minus sign, which reads as a sign rather than a dash. - static func dBm(_ rssi: Int) -> String { - rssi < 0 ? "\u{2212}\(-rssi) dBm" : "\(rssi) dBm" - } - - // The tab's document, schema 1. - static func document(_ s: Snapshot) -> [String: Any] { - let silence = s.config.silenceSeconds - let ago = s.heard.map { max(0, Int(s.now.timeIntervalSince($0))) } - let silent = ago.map { $0 > silence } ?? false - - let badge: (String, String) - if let issue = s.issue { - badge = (issue, "warning") - } else { - switch s.phone { - case .notChosen: badge = ("No phone chosen", "neutral") - case .notPaired: badge = ("Phone not paired", "warning") - case .notFound: badge = ("Looking for phone", "neutral") - case .ambiguous: badge = ("Rename your phone", "warning") - case .bound: - if s.state == .away { badge = ("Away", "warning") } - else if silent || ago == nil { badge = ("Phone silent", "neutral") } - else { badge = ("Present", "success") } - } - } - let header: [String: Any] = [ - "title": "Away", - "badge": ["text": badge.0, "tone": badge.1], - "trailing": "idle \(Tab.duration(s.config.idleSeconds)) · silent \(Tab.duration(silence))", - ] - - var rows: [[String: Any]] = [] - if let name = s.config.phone { - var row: [String: Any] = ["id": "phone", "title": name, "subtitle": "Your phone"] - switch s.phone { - case .notChosen: - break - case .notPaired: - row["value"] = "not paired" - row["footnote"] = "Pair it in System Settings \u{2192} Bluetooth. Away can't " - + "recognise an unpaired phone, so it never locks." - case .ambiguous(let count): - row["value"] = "\(count) devices" - row["footnote"] = "\(count) devices named \(name) nearby \u{2014} rename your phone " - + "so Away can tell which is yours. It won't lock until then." - case .notFound: - row["value"] = "not heard yet" - row["footnote"] = "Paired, but not heard. Keep it nearby and unlocked for a moment." - case .bound: - if let ago, let rssi = s.rssi, !silent { - row["value"] = ago < 2 ? "\(Tab.dBm(rssi)) · just now" - : "\(Tab.dBm(rssi)) · \(Tab.duration(ago)) ago" - row["footnote"] = "Its Bluetooth signal, not a connection: heard every few " - + "seconds in use, up to a minute or more lying idle." - row["track"] = ["fill": signalFill(rssi), "tint": "#7FD1B9"] - } else if let ago { - row["value"] = "not heard for \(Tab.duration(ago))" - row["footnote"] = "Silent longer than \(Tab.duration(silence)), so it counts " - + "as gone while the Mac is idle." - } else { - row["value"] = "not heard yet" - row["footnote"] = "Waiting to hear it again." - } - } - rows.append(row) - } - // Strongest first, a dozen at most: enough to find your own phone in a - // busy office, and a line that stays far under the host's limit. - for device in s.others.sorted(by: { ($0.rssi, $0.name) > ($1.rssi, $1.name) }).prefix(12) { - rows.append([ - "id": "device-\(device.id.uuidString)", - "title": device.name, - "subtitle": "Paired, nearby", - "value": Tab.dBm(device.rssi), - "footnote": "set Phone to this name to use it", - "track": ["fill": signalFill(device.rssi), "tint": "#8A8A8A"], - ]) - } - - var document: [String: Any] = ["schema": 1, "header": header, "rows": rows] - if rows.isEmpty { - document["state"] = "empty" - document["message"] = s.issue != nil || !s.scanning - ? "Bluetooth isn't scanning, so no devices can be listed." - : "No paired devices heard yet. Keep your phone nearby and unlocked for a moment." - } - return document - } - - // A bar from -100 dBm (empty) to -40 dBm (full). Only a rough picture: - // readings swing by 15 dB lying still. - static func signalFill(_ rssi: Int) -> Double { - min(max(Double(rssi + 100) / 60, 0), 1) - } -} - -// MARK: - Choices - -// What Settings offers for the Phone key: the paired devices heard lately, -// sent to the host as a `choices` message (the key is declared "dynamic"). -// The value is the name exactly as it matched, so picking one saves a name -// that matches; the configured phone is always in the list, heard or not, so -// Settings can show what's set. -enum PhoneChoices { - // The host's limits for a choices message: more options, a longer value - // or label, or a value with a line break or control character in it, and - // it refuses the whole message. So one odd device name is left out here - // rather than costing every other choice. - static let maxOptions = 64 - static let maxLength = 256 - // Room for " · −100 dBm" after the name, within maxLength. - static let maxNameLength = maxLength - 16 - - static func usable(_ name: String) -> String? { - let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines) - guard !trimmed.isEmpty, trimmed.count <= maxNameLength, - !trimmed.unicodeScalars.contains(where: { - CharacterSet.controlCharacters.contains($0) || CharacterSet.newlines.contains($0) - || CharacterSet.illegalCharacters.contains($0) - }) - else { return nil } - return trimmed - } - - static func options(nearby: [Nearby], configured: String?) -> [[String: String]] { - let configured = configured.flatMap(usable) - let wanted = configured.map(PhoneName.normalised) - // One entry per name, the strongest reading: a phone can show up under - // a fresh identifier while the old one is still remembered. - var strongest: [String: Nearby] = [:] - for var device in nearby { - guard let usableName = usable(device.name) else { continue } - device = Nearby(id: device.id, name: usableName, rssi: device.rssi, lastSeen: device.lastSeen) - let name = PhoneName.normalised(device.name) - if let seen = strongest[name], seen.rssi >= device.rssi { continue } - strongest[name] = device - } - var options: [[String: String]] = strongest.values - .sorted { ($0.name.lowercased(), $0.id.uuidString) < ($1.name.lowercased(), $1.id.uuidString) } - .map { device in - // The configured spelling, when it's this device, so the saved - // value is the one Settings finds selected. - let isConfigured = PhoneName.normalised(device.name) == wanted - let value = isConfigured ? (configured ?? device.name) : device.name - return ["value": value, "label": "\(value) · \(Tab.dBm(device.rssi))"] - } - if let configured, !strongest.keys.contains(PhoneName.normalised(configured)) { - options.insert(["value": configured, "label": "\(configured) · not heard"], at: 0) - } - return Array(options.prefix(maxOptions)) - } - - static func message(_ options: [[String: String]]) -> [String: Any] { - ["type": "choices", "key": AwayConfig.phoneKey, "options": options] - } -} - -// MARK: - The scan - -// Owns the CoreBluetooth scan, the tracker and everything the tab shows. -// Main-thread only: the central manager delivers on the main queue, and stdin -// lines are hopped there before they reach this. -final class Away: NSObject, CBCentralManagerDelegate { - - private var config = AwayConfig(values: [:]) - private var mayHoldPresence = false - private var central: CBCentralManager? - private var tracker = PresenceTracker(rule: AwayConfig(values: [:]).rule) - private var binding = PhoneBinding() - private var phone: Snapshot.Phone = .notChosen - private var sleepGap = SleepGap() - private var targetRSSI: Int? - private var targetHeard: Date? - private var nearby: [UUID: Nearby] = [:] - // Normalised, as PhoneName compares them. - private var pairedNames: Set = [] - private var pairedNamesAt = Date.distantPast - private var bluetoothIssue: String? - private var reported: PresenceState? - private var lastDocument: Data? - private var lastDocumentAt = Date.distantPast - private var timer: Timer? - private var offered: [[String: String]]? - private var offeredAt = Date.distantPast - // Nothing goes to stdout before `ready`: the host reads the first line as - // the answer to its hello. - private var ready = false - - // `hello`. Starting the scan is what asks for Bluetooth permission, so - // nothing touches CoreBluetooth before the host has said hello. - func start(granted: [String], values: [String: String]) { - mayHoldPresence = granted.contains("signal:presence") - configure(values) - ready = true - Out.send(["type": "ready", "protocol": 1]) - report(.present) - central = CBCentralManager(delegate: self, queue: nil) - timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { [weak self] _ in - self?.tick() - } - // The clock-gap check catches a sleep whether or not these arrive. - let workspace = NSWorkspace.shared.notificationCenter - for name in [NSWorkspace.willSleepNotification, NSWorkspace.didWakeNotification] { - workspace.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in - self?.forgetHeard(because: "the Mac slept") - } - } - publish(force: true) - } - - // `config`, and the environment at launch. A new phone name forgets the - // old one's identifier and everything heard from it; a new wait or silence - // keeps what's been heard, so it applies at once. - func configure(_ values: [String: String]) { - let next = AwayConfig(values: values) - if next.phone.map(PhoneName.normalised) != config.phone.map(PhoneName.normalised) { - binding = PhoneBinding() - targetRSSI = nil - targetHeard = nil - tracker = PresenceTracker(rule: tracker.rule) - // Nothing is known about the new phone yet, and nothing gets - // judged until it's found, so an "away" about the old one must - // not stand in the meantime. - report(.present) - } - tracker.rule = next.rule - config = next - // Re-read, so the paired check sees the new name straight away. - pairedNamesAt = .distantPast - tick() - } - - // Seconds since the last keyboard, mouse or trackpad event in this login - // session. Needs no permission: it's a count, not the events themselves. - static func idleSeconds() -> TimeInterval { - CGEventSource.secondsSinceLastEventType(.combinedSessionState, - eventType: CGEventType(rawValue: ~0)!) - } - - private func forgetHeard(because why: String) { - tracker.forgetHeard() - FileHandle.standardError.write(Data("away: forgot the phone's last signal: \(why)\n".utf8)) - } - - private func tick() { - let now = Date() - if sleepGap.slept(tickAt: now) { forgetHeard(because: "the clock jumped") } - refreshPairedNames(now) - phone = currentPhone(now) - switch phone { - case .bound: - report(tracker.evaluate(now: now, idle: Self.idleSeconds())) - case .ambiguous, .notPaired, .notFound, .notChosen: - // Nothing to judge, or nothing certain: never away. - report(.present) - } - publish() - } - - private func currentPhone(_ now: Date) -> Snapshot.Phone { - guard let name = config.phone else { return .notChosen } - guard pairedNames.contains(PhoneName.normalised(name)) else { return .notPaired } - switch binding.resolve(now: now, window: TimeInterval(config.silenceSeconds), following: &tracker) { - case .notFound: return .notFound - case .ambiguous(let count): return .ambiguous(count: count) - case .bound: return .bound - } - } - - private func refreshPairedNames(_ now: Date) { - // Re-read now and then, so a phone paired after this started shows up. - guard now.timeIntervalSince(pairedNamesAt) >= 30 else { return } - pairedNames = Self.pairedDeviceNames() - pairedNamesAt = now - } - - // The signal, only when it changes, so the app reacts once per change. - private func report(_ state: PresenceState) { - guard ready, state != reported else { return } - reported = state - FileHandle.standardError.write(Data("away: \(state)\n".utf8)) - guard mayHoldPresence else { return } - Out.send(["type": "signal", "name": "presence", - "value": state == .away ? "away" : "present"]) - } - - // MARK: CoreBluetooth - - static func issue(for state: CBManagerState) -> String? { - switch state { - case .poweredOn: return nil - case .poweredOff: return "Bluetooth off" - case .unauthorized: return "Bluetooth not allowed" - case .unsupported: return "No Bluetooth LE" - case .resetting, .unknown: return nil - @unknown default: return nil - } - } - - func centralManagerDidUpdateState(_ central: CBCentralManager) { - bluetoothIssue = Self.issue(for: central.state) - guard central.state == .poweredOn else { - // Nothing heard while Bluetooth is off says nothing about where the - // phone is, so forget it rather than count the silence. - tracker = PresenceTracker(rule: tracker.rule) - targetRSSI = nil - targetHeard = nil - nearby = [:] - report(.present) - publish(force: true) - return - } - // Duplicates on: each advertisement is a reading, not just the first. - central.scanForPeripherals(withServices: nil, - options: [CBCentralManagerScanOptionAllowDuplicatesKey: true]) - publish(force: true) - } - - func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, - advertisementData: [String: Any], rssi RSSI: NSNumber) { - let now = Date() - let rssi = RSSI.intValue - refreshPairedNames(now) - guard let name = peripheral.name ?? advertisementData[CBAdvertisementDataLocalNameKey] as? String, - !name.isEmpty else { return } - let normalised = PhoneName.normalised(name) - // Only a paired device can be the phone, or be listed. CoreBluetooth - // has no public way from a scan result to a pairing, so it goes by the - // name the pairing recorded, which is also the name a paired phone - // advertises. - guard pairedNames.contains(normalised) else { return } - - // Only an advert with a reading counts as hearing it, here as in the - // tracker and the list: the binding's sightings are what the tracker - // catches up to. - if let phone = config.phone, rssi < 0, normalised == PhoneName.normalised(phone) { - binding.observe(peripheral.identifier, at: now) - if case .bound = currentPhone(now), peripheral.identifier == binding.bound { - tracker.observe(rssi: rssi, at: now) - if rssi < 0 { - targetRSSI = rssi - targetHeard = now - } - // Coming back on a strong reading is reported straight away, - // not on the next tick, so the app hears it as soon as possible. - if tracker.state == .present, reported == .away { report(.present) } - } - } - - // The list the user copies the name from: paired, named, heard lately. - guard rssi < 0 else { return } - nearby[peripheral.identifier] = Nearby(id: peripheral.identifier, name: name, - rssi: rssi, lastSeen: now) - } - - static func pairedDeviceNames() -> Set { - let paired = (IOBluetoothDevice.pairedDevices() as? [IOBluetoothDevice]) ?? [] - return Set(paired.compactMap { $0.name }.filter { !$0.isEmpty }.map(PhoneName.normalised)) - } - - // MARK: The tab - - // At most every 2 s, and only when what it shows changed. A busy room - // advertises many times a second; the tab needn't redraw that often. - private func publish(force: Bool = false) { - let now = Date() - guard ready, force || now.timeIntervalSince(lastDocumentAt) >= 2 else { return } - nearby = nearby.filter { now.timeIntervalSince($0.value.lastSeen) < 60 } - offerChoices(now) - let bound = binding.bound - let document = Tab.document(Snapshot( - config: config, issue: bluetoothIssue, scanning: central != nil, phone: phone, - state: reported ?? .present, rssi: targetRSSI, heard: targetHeard, - others: nearby.values.filter { $0.id != bound }, now: now)) - guard let data = Out.line(["type": "document", "document": document]), - data != lastDocument else { return } - lastDocument = data - lastDocumentAt = now - Out.send(["type": "document", "document": document]) - } - - // Sent when the devices on offer change, and otherwise at most every 10 s - // to keep the signal strengths in the labels roughly current. publish - // already holds this to once every 2 s. - private func offerChoices(_ now: Date) { - let options = PhoneChoices.options(nearby: Array(nearby.values), configured: config.phone) - let values = options.map { $0["value"] ?? "" } - let changedSet = values != (offered?.map { $0["value"] ?? "" } ?? []) - guard offered == nil || changedSet - || (options != offered! && now.timeIntervalSince(offeredAt) >= 10) else { return } - offered = options - offeredAt = now - Out.send(PhoneChoices.message(options)) - } -} - -// MARK: - stdin - -// Lines from the host, read on a background thread and handled on main, where -// CoreBluetooth and the timer live. -func readHost(_ away: Away) { - let thread = Thread { - var started = false - while let line = readLine(strippingNewline: true) { - guard let data = line.data(using: .utf8), - let object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any], - let type = object["type"] as? String else { continue } - DispatchQueue.main.async { - switch type { - case "hello": - guard !started else { return } - started = true - let granted = object["capabilities"] as? [String] ?? [] - away.start(granted: granted, values: ProcessInfo.processInfo.environment) - case "config": - away.configure(object["values"] as? [String: String] ?? [:]) - case "ping": - // Echoed as it came: the host matches it to the ping it sent. - Out.send(["type": "pong", "id": object["id"] ?? 0]) - case "stop": - exit(0) - default: - // Unknown types are how the protocol grows; skip them. - break - } - } - } - // stdin closed: the host has gone, and nobody is left to tell. - DispatchQueue.main.async { exit(0) } - } - thread.start() -} - -// MARK: - Self-test - -// Replays recorded timings through the rule, for scripts/test-extensions.sh -// (via test_away.py). Exits non-zero on any failure, naming each. -func selfTest() -> Int32 { - var failures = 0 - func check(_ ok: Bool, _ what: String) { - if !ok { - failures += 1 - print("FAIL: \(what)") - } - } - let start = Date(timeIntervalSince1970: 1_700_000_000) - func at(_ s: Double) -> Date { start.addingTimeInterval(s) } - func rule(idle: Double, silence: Double) -> PresenceTracker.Rule { - PresenceTracker.Rule(idle: idle, silence: silence) - } - - // The desk recording: an idle phone lying beside the Mac, with gaps of 66 - // and 75 s between advertisements and weak readings. Nobody touches the - // Mac. With a 10 s wait and the shortest silence allowed (90 s) it must - // never count as away. - do { - var tracker = PresenceTracker(rule: rule(idle: 10, silence: 90)) - let adverts: [(Double, Int)] = [(0, -60), (6, -71), (12, -95), (15, -99)] - + stride(from: 81.0, through: 146, by: 5).map { ($0, -88) } - + [(221, -93), (225, -70)] - var next = 0 - var everAway = false - // Up to 300 s: 75 s after the last advert, still short of the 90 s. - for second in 0...300 { - let now = at(Double(second)) - while next < adverts.count, adverts[next].0 <= Double(second) { - tracker.observe(rssi: adverts[next].1, at: now) - next += 1 - } - if tracker.evaluate(now: now, idle: Double(second)) == .away { everAway = true } - } - check(!everAway, "the desk recording counted as away") - } - - // The silence while idle is away; a strong advert is back. - do { - var tracker = PresenceTracker(rule: rule(idle: 10, silence: 120)) - tracker.observe(rssi: -60, at: at(0)) - check(tracker.evaluate(now: at(119), idle: 119) == .present, "away before 120 s of silence") - check(tracker.evaluate(now: at(120), idle: 120) == .away, "not away after 120 s of silence") - tracker.observe(rssi: -85, at: at(125)) - check(tracker.state == .away, "a weak -85 advert brought you back") - tracker.observe(rssi: -72, at: at(130)) - check(tracker.state == .present, "a -72 advert didn't bring you back") - } - - // Idle and silence are independent: a short wait doesn't stretch the - // silence, and a long silence isn't shortened by a short wait. - do { - var tracker = PresenceTracker(rule: rule(idle: 10, silence: 90)) - tracker.observe(rssi: -60, at: at(0)) - check(tracker.evaluate(now: at(89), idle: 89) == .present, "away before 90 s of silence") - check(tracker.evaluate(now: at(90), idle: 90) == .away, "not away after 90 s of silence") - - var long = PresenceTracker(rule: rule(idle: 30, silence: 600)) - long.observe(rssi: -60, at: at(0)) - check(long.evaluate(now: at(599), idle: 599) == .present, "away before 600 s of silence") - check(long.evaluate(now: at(600), idle: 600) == .away, "not away after 600 s of silence") - - var idle = PresenceTracker(rule: rule(idle: 120, silence: 90)) - idle.observe(rssi: -60, at: at(0)) - check(idle.evaluate(now: at(100), idle: 100) == .present, "away before the idle wait") - check(idle.evaluate(now: at(120), idle: 120) == .away, "not away once idle long enough") - } - - // Typing always means present, however long the phone has been silent. - do { - var tracker = PresenceTracker(rule: rule(idle: 30, silence: 120)) - tracker.observe(rssi: -60, at: at(0)) - check(tracker.evaluate(now: at(600), idle: 5) == .present, "away while typing") - } - - // A phone gone for good locks once: after input brings you back, a long - // idle with no advert stays present until the phone is heard again. - do { - var tracker = PresenceTracker(rule: rule(idle: 10, silence: 120)) - tracker.observe(rssi: -60, at: at(0)) - check(tracker.evaluate(now: at(130), idle: 130) == .away, "never went away") - check(tracker.evaluate(now: at(140), idle: 0) == .present, "input didn't bring you back") - check(tracker.evaluate(now: at(500), idle: 360) == .present, "locked twice for one departure") - } - - // Sleep. The phone was heard just before the lid closed; the first tick - // after waking comes 20 minutes later, idle the whole time. The silence - // was the Mac's, not the phone's, so it must not lock, and it stays - // present until the phone has been heard afresh and gone quiet again. - do { - var tracker = PresenceTracker(rule: rule(idle: 10, silence: 120)) - var gap = SleepGap() - tracker.observe(rssi: -60, at: at(0)) - for second in 0...30 { - if gap.slept(tickAt: at(Double(second))) { tracker.forgetHeard() } - tracker.evaluate(now: at(Double(second)), idle: Double(second)) - } - check(!gap.slept(tickAt: at(31)), "a one-second tick read as a sleep") - let woke = at(1231) - if gap.slept(tickAt: woke) { tracker.forgetHeard() } else { check(false, "missed the sleep") } - check(tracker.evaluate(now: woke, idle: 1231) == .present, "locked on waking from sleep") - check(tracker.evaluate(now: at(1500), idle: 1500) == .present, "locked later without a new advert") - tracker.observe(rssi: -60, at: at(1510)) - check(tracker.evaluate(now: at(1630), idle: 1630) == .away, "a fresh silence after waking didn't count") - } - - // Which device is the phone. - do { - let mine = UUID(), other = UUID(), rotated = UUID() - var binding = PhoneBinding() - check(binding.resolve(now: at(0), window: 120) == .notFound, "bound to nothing heard") - binding.observe(mine, at: at(0)) - check(binding.resolve(now: at(1), window: 120) == .bound(mine), "didn't bind the only one") - - // A second device with the name: neither, until one has been silent - // for the window. - binding.observe(other, at: at(10)) - check(binding.resolve(now: at(11), window: 120) == .ambiguous(count: 2), "bound with two") - binding.observe(mine, at: at(50)) - binding.observe(other, at: at(100)) - check(binding.resolve(now: at(101), window: 120) == .ambiguous(count: 2), "still two") - binding.observe(other, at: at(200)) - check(binding.resolve(now: at(200), window: 120) == .bound(other), - "didn't move to the one still heard once the bound one went silent") - - // Two seen at once from the start binds to neither. - var fresh = PhoneBinding() - fresh.observe(mine, at: at(0)) - fresh.observe(rotated, at: at(0)) - check(fresh.resolve(now: at(1), window: 120) == .ambiguous(count: 2), "bound when ambiguous") - check(fresh.bound == nil, "kept a binding while ambiguous") - - // The bound one simply going quiet stays bound: that's how away happens. - var quiet = PhoneBinding() - quiet.observe(mine, at: at(0)) - _ = quiet.resolve(now: at(0), window: 120) - check(quiet.resolve(now: at(300), window: 120) == .bound(mine), "dropped a silent phone") - } - - // The phone moves to a new identifier while it stays in the room, and - // you've been idle all along. Moving to it mustn't lock: the silence - // counts from the new identifier's last sighting. - do { - let old = UUID(), new = UUID() - var binding = PhoneBinding() - var tracker = PresenceTracker(rule: rule(idle: 15, silence: 90)) - // As the app runs it: a tick a second, and the new identifier - // advertising every 10 s from 10 s on. - var states: [PresenceState] = [] - for t in stride(from: 0.0, through: 125, by: 1) { - if case .bound = binding.resolve(now: at(t), window: 90, following: &tracker) { - states.append(tracker.evaluate(now: at(t), idle: t)) - } - let id: UUID? = t == 0 ? old : (t.truncatingRemainder(dividingBy: 10) == 0 ? new : nil) - if let id { - binding.observe(id, at: at(t)) - if binding.resolve(now: at(t), window: 90, following: &tracker) == .bound(id) { - tracker.observe(rssi: -60, at: at(t)) - } - } - } - check(binding.bound == new, "didn't move to the new identifier") - check(!states.contains(.away), "locked when the phone moved to a new identifier") - - // And the new one then going silent still counts. - _ = binding.resolve(now: at(215), window: 90, following: &tracker) - check(tracker.evaluate(now: at(215), idle: 215) == .away, "the new identifier's silence didn't count") - } - - // Moving to a new identifier straight after a sleep doesn't bring back a - // sighting from before it: the phone has to be heard afresh. - do { - let old = UUID(), new = UUID() - var binding = PhoneBinding() - var tracker = PresenceTracker(rule: rule(idle: 15, silence: 90)) - binding.observe(old, at: at(0)) - _ = binding.resolve(now: at(0), window: 90, following: &tracker) - tracker.observe(rssi: -60, at: at(0)) - binding.observe(new, at: at(50)) - // Asleep from 60 to 100, then the first tick forgets, then resolves. - tracker.forgetHeard() - check(binding.resolve(now: at(100), window: 90, following: &tracker) == .bound(new), "didn't move after the sleep") - check(tracker.lastSeen == nil, "brought back a sighting from before the sleep") - check(tracker.evaluate(now: at(145), idle: 145) == .present, "counted the sleep as silence") - } - - // Another device with the name is heard once, and the ambiguity ends on - // the same identifier. Its adverts in between weren't passed on, and - // mustn't count as silence. - do { - let mine = UUID(), other = UUID() - var binding = PhoneBinding() - var tracker = PresenceTracker(rule: rule(idle: 15, silence: 90)) - var states: [PresenceState] = [] - for t in stride(from: 0.0, through: 130, by: 1) { - if case .bound = binding.resolve(now: at(t), window: 90, following: &tracker) { - states.append(tracker.evaluate(now: at(t), idle: t)) - } - if t == 5 { binding.observe(other, at: at(t)) } - if t.truncatingRemainder(dividingBy: 10) == 0 { - binding.observe(mine, at: at(t)) - if binding.resolve(now: at(t), window: 90, following: &tracker) == .bound(mine) { - tracker.observe(rssi: -60, at: at(t)) - } - } - } - check(binding.bound == mine, "didn't settle back on the phone") - check(!states.contains(.away), "locked after ambiguity ended on the same identifier") - - // And catching up doesn't hold it off once the phone really goes: - // last heard at 130, so away from 220. - _ = binding.resolve(now: at(219), window: 90, following: &tracker) - check(tracker.evaluate(now: at(219), idle: 219) == .present, "locked before the silence was up") - _ = binding.resolve(now: at(220), window: 90, following: &tracker) - check(tracker.evaluate(now: at(220), idle: 220) == .away, "the phone going after the ambiguity didn't count") - } - - // Names compare loosely. - check(PhoneName.normalised("Alex\u{2019}s Pixel 9 ") == PhoneName.normalised("alex's pixel 9"), - "curly apostrophe, case or space made a different name") - check(PhoneName.normalised("Alex\u{2018}s") == "alex's", "left single quote") - - // Config: unset is the default, out of range is clamped, junk is ignored. - check(AwayConfig(values: [:]).idleSeconds == 30, "idle default") - check(AwayConfig(values: [AwayConfig.idleKey: "3"]).idleSeconds == 10, "idle floor") - check(AwayConfig(values: [AwayConfig.idleKey: "900"]).idleSeconds == 120, "idle ceiling") - check(AwayConfig(values: [AwayConfig.idleKey: "soon"]).idleSeconds == 30, "idle junk") - check(AwayConfig(values: [:]).silenceSeconds == 120, "silence default") - check(AwayConfig(values: [AwayConfig.silenceKey: "30"]).silenceSeconds == 90, "silence floor") - check(AwayConfig(values: [AwayConfig.silenceKey: "9000"]).silenceSeconds == 600, "silence ceiling") - check(AwayConfig(values: [AwayConfig.silenceKey: "300"]).rule.missingAfter == 300, "silence rule") - check(AwayConfig(values: [AwayConfig.idleKey: "45"]).rule.idleAtLeast == 45, "idle rule") - check(AwayConfig(values: [AwayConfig.phoneKey: " "]).phone == nil, "blank phone") - - // The phone row and badge say what's going on. - do { - let config = AwayConfig(values: [AwayConfig.phoneKey: "Pixel"]) - func phoneRow(_ phone: Snapshot.Phone, state: PresenceState = .present, rssi: Int? = -75, - heard: Date? = at(0), now: Date = at(3)) -> (badge: String, value: String) { - let document = Tab.document(Snapshot(config: config, issue: nil, scanning: true, - phone: phone, state: state, rssi: rssi, - heard: heard, others: [], now: now)) - let header = document["header"] as? [String: Any] - let badge = (header?["badge"] as? [String: Any])?["text"] as? String ?? "" - let row = (document["rows"] as? [[String: Any]])?.first - return (badge, row?["value"] as? String ?? "") - } - check(phoneRow(.bound) == ("Present", "\u{2212}75 dBm · 3 s ago"), "heard row") - check(phoneRow(.bound, now: at(240)) == ("Phone silent", "not heard for 4 min"), "silent row") - check(phoneRow(.bound, state: .away, now: at(240)) == ("Away", "not heard for 4 min"), "away row") - check(phoneRow(.notPaired) == ("Phone not paired", "not paired"), "unpaired row") - check(phoneRow(.ambiguous(count: 2)) == ("Rename your phone", "2 devices"), "ambiguous row") - check(phoneRow(.notFound, rssi: nil, heard: nil) == ("Looking for phone", "not heard yet"), - "not found row") - } - - // The phone choices: one per name, the configured spelling kept, and the - // configured phone listed even when it isn't heard. - do { - let a = UUID(), b = UUID(), c = UUID() - let heard = [Nearby(id: a, name: "Alex's Pixel 9", rssi: -74, lastSeen: at(0)), - Nearby(id: b, name: "Alex's Pixel 9", rssi: -90, lastSeen: at(0)), - Nearby(id: c, name: "Headphones", rssi: -40, lastSeen: at(0))] - let options = PhoneChoices.options(nearby: heard, configured: "Alex\u{2019}s Pixel 9") - check(options.map { $0["value"] ?? "" } == ["Alex\u{2019}s Pixel 9", "Headphones"], - "choices aren't one per name in the configured spelling: \(options)") - check(options.first?["label"] == "Alex\u{2019}s Pixel 9 · \u{2212}74 dBm", - "the choice label isn't name · strongest signal") - let gone = PhoneChoices.options(nearby: [heard[2]], configured: "Pixel") - check(gone.map { $0["value"] ?? "" } == ["Pixel", "Headphones"], "lost the configured phone") - check(gone.first?["label"] == "Pixel · not heard", "the unheard phone isn't labelled so") - check(PhoneChoices.options(nearby: [], configured: nil).isEmpty, "offered nothing heard") - let line = Out.line(PhoneChoices.message(options)) ?? Data() - let decoded = (try? JSONSerialization.jsonObject(with: line)) as? [String: Any] - check(decoded?["type"] as? String == "choices" && decoded?["key"] as? String == AwayConfig.phoneKey, - "the choices message isn't for the phone key") - let crowd = (0..<200).map { Nearby(id: UUID(), name: String(repeating: "y", count: 200) + "\($0)", - rssi: -60, lastSeen: at(0)) } - let many = PhoneChoices.options(nearby: crowd, configured: nil) - check(many.count == PhoneChoices.maxOptions, "choices over the host's cap") - - // Odd names are tidied or left out, never sent to be refused. - let odd = [Nearby(id: UUID(), name: " Pixel \n", rssi: -60, lastSeen: at(0)), - Nearby(id: UUID(), name: " ", rssi: -60, lastSeen: at(0)), - Nearby(id: UUID(), name: "bad\u{0}name", rssi: -60, lastSeen: at(0)), - Nearby(id: UUID(), name: "a\u{2028}b", rssi: -60, lastSeen: at(0)), - Nearby(id: UUID(), name: String(repeating: "z", count: 300), rssi: -60, lastSeen: at(0))] - let tidy = PhoneChoices.options(nearby: odd, configured: nil) - check(tidy.map { $0["value"] ?? "" } == ["Pixel"], "odd device names weren't tidied: \(tidy)") - check(tidy.allSatisfy { ($0["label"] ?? "").count <= PhoneChoices.maxLength - && ($0["value"] ?? "").count <= PhoneChoices.maxLength }, - "a choice over the host's length limit") - check((Out.line(PhoneChoices.message(many)) ?? Data()).count < Out.maxLineBytes, "choices line over 64 KB") - } - - // The document stays far under the host's 64 KB line limit even with a - // crowded room of long names. - do { - let crowd = (0..<200).map { - Nearby(id: UUID(), name: String(repeating: "x", count: 200) + "\($0)", - rssi: -50 - $0 % 40, lastSeen: at(0)) - } - let document = Tab.document(Snapshot( - config: AwayConfig(values: [AwayConfig.phoneKey: "Phone"]), issue: nil, scanning: true, - phone: .bound, state: .present, rssi: -60, heard: at(0), others: crowd, now: at(1))) - let line = Out.line(["type": "document", "document": document]) ?? Data() - check(!line.isEmpty && line.count < Out.maxLineBytes, "document line over 64 KB") - } - - print(failures == 0 ? "away self-test: ok" : "away self-test: \(failures) failed") - return failures == 0 ? 0 : 1 -} - -// MARK: - Main - -if CommandLine.arguments.dropFirst().first == "--self-test" { - exit(selfTest()) -} - -let away = Away() -readHost(away) -RunLoop.main.run() diff --git a/extensions/away/manifest.json b/extensions/away/manifest.json deleted file mode 100644 index f88ad63..0000000 --- a/extensions/away/manifest.json +++ /dev/null @@ -1,64 +0,0 @@ -{ - "id": "away", - "name": "Away", - "description": "Locks the Mac when your phone leaves", - "version": "1.1.1", - "schema": 2, - "mode": "service", - "surfaces": [ - "settings" - ], - "capabilities": [ - "bluetooth", - "signal:presence" - ], - "tab": { - "label": "Away" - }, - "run": "./run", - "requires": [ - "swiftc" - ], - "handshakeSeconds": 90, - "config": [ - { - "key": "STACKNUDGE_EXT_AWAY_PHONE", - "label": "Phone", - "help": "Your phone, from the paired devices Away can hear nearby. It has to be paired with this Mac in System Settings → Bluetooth.", - "type": "dynamic" - }, - { - "key": "STACKNUDGE_EXT_AWAY_IDLE", - "label": "Idle for", - "help": "How long the Mac must go untouched before you can count as away.", - "type": "number", - "options": [ - 10, - 15, - 20, - 30, - 45, - 60, - 90, - 120 - ], - "unit": "seconds", - "default": 30 - }, - { - "key": "STACKNUDGE_EXT_AWAY_SILENCE", - "label": "Phone silent for", - "help": "How long the phone must go unheard before you can count as away. A phone lying idle on a desk was measured going 75 s between signals, so nothing shorter than 90 s is offered.", - "type": "number", - "options": [ - 90, - 120, - 180, - 300, - 600 - ], - "unit": "seconds", - "default": 120 - } - ] -} diff --git a/extensions/away/run b/extensions/away/run deleted file mode 100755 index 92f216b..0000000 --- a/extensions/away/run +++ /dev/null @@ -1,54 +0,0 @@ -#!/usr/bin/env bash -# -# Starts the Away service, building it first if needed. -# -# Away needs CoreBluetooth, which no script language here can reach, so it is a -# small Swift program. It's compiled on this Mac from away.swift rather than -# shipped as a binary: nothing opaque lands in the repository or the release, -# the reviewer reads exactly what runs, and the Command Line Tools that provide -# swiftc are already on any Mac that runs a coding agent (git needs them). The -# cost is the first start after an install or update: about 3 s with a warm -# module cache, but 15 s or more with a cold one, which is why the manifest asks -# for a 90 s handshake rather than the host's usual 10 s. -# -# stdout belongs to the line protocol from the moment this starts, so the -# compiler's output, and anything else said here, goes to stderr. - -set -euo pipefail - -# The host starts this in the extension's own directory, but resolve it anyway -# so running it by path from anywhere works the same. No dirname: the host's -# PATH is minimal, and a builtin can't go missing. -here="$(cd "${BASH_SOURCE[0]%/*}" && pwd)" -src="$here/away.swift" -build="$here/.build" -bin="$build/away" - -if [[ ! -x "$bin" || "$src" -nt "$bin" ]]; then - # A build the host killed leaves its partial file behind (see below), so any - # whose process is gone are cleared before trying again. - for old in "$build"/away.*; do - pid="${old##*.}" - if [[ "$pid" =~ ^[0-9]+$ ]] && ! kill -0 "$pid" 2> /dev/null; then - rm -f "${old:?}" - fi - done - if ! command -v swiftc > /dev/null 2>&1; then - echo "away: swiftc not found; install the Command Line Tools (xcode-select --install)" >&2 - exit 69 - fi - mkdir -p "$build" - # Built beside the real path under a name only this process uses, and moved - # into place, so a build the host cuts short (it kills a start that doesn't - # answer in time) never leaves a half-written binary that looks current, and - # two launches at once never write or remove each other's. - tmp="$build/away.$$" - if ! swiftc -O "$src" -o "$tmp" >&2; then - rm -f "${tmp:?}" - echo "away: couldn't build away.swift" >&2 - exit 70 - fi - mv -f "$tmp" "$bin" -fi - -exec "$bin" "$@" diff --git a/extensions/away/test_away.py b/extensions/away/test_away.py deleted file mode 100644 index f9c3877..0000000 --- a/extensions/away/test_away.py +++ /dev/null @@ -1,180 +0,0 @@ -#!/usr/bin/env python3 -"""Tests for the Away service extension. - -Run them with `scripts/test-extensions.sh`, which is what CI does. - -Away is Swift, because it needs CoreBluetooth, so most of what's worth testing -lives in the program itself: `away --self-test` replays recorded advertisement -timings through the presence rule and exits non-zero on a failure. These tests -build it and run that, check the line protocol without starting a Bluetooth -scan, and check the launcher fails cleanly where it can't build. - -The Swift parts need macOS and are skipped elsewhere (CI validates extensions -on Linux). The launcher and manifest tests run everywhere. -""" - -import json -import os -import pathlib -import shutil -import subprocess -import sys -import tempfile -import unittest - -HERE = pathlib.Path(__file__).resolve().parent -ON_MAC = sys.platform == "darwin" - - -def build(into): - """Compiles away.swift the way ./run does, into a scratch directory, so a - test never leaves a build behind in the extension itself.""" - binary = pathlib.Path(into) / "away" - subprocess.run(["swiftc", "-O", str(HERE / "away.swift"), "-o", str(binary)], - check=True, capture_output=True, timeout=300) - return binary - - -@unittest.skipUnless(ON_MAC and shutil.which("swiftc"), "needs macOS and swiftc") -class Program(unittest.TestCase): - - @classmethod - def setUpClass(cls): - cls.scratch = tempfile.mkdtemp(prefix="away-test-") - cls.binary = build(cls.scratch) - - @classmethod - def tearDownClass(cls): - shutil.rmtree(cls.scratch, ignore_errors=True) - - def test_the_presence_rule_passes_its_self_test(self): - # The desk recording (gaps of 66 and 75 s, readings down to -99) never - # counts as away, even at the shortest silence; the configured silence - # while idle does; a -72 advert brings you back and a -85 one doesn't; - # a phone gone for good locks once; waking from sleep doesn't lock; - # two devices with the phone's name bind to neither; names compare - # loosely; the phone row reads as a signal. See selfTest() in away.swift. - result = subprocess.run([str(self.binary), "--self-test"], - capture_output=True, text=True, timeout=30) - self.assertEqual(result.returncode, 0, result.stdout + result.stderr) - self.assertIn("away self-test: ok", result.stdout) - - def test_before_hello_it_answers_pings_skips_unknown_types_and_stops(self): - # No hello, so no Bluetooth scan starts: this is the protocol alone. - lines = [ - {"type": "something-from-a-newer-host", "x": 1}, - {"type": "ping", "id": 17}, - {"type": "stop"}, - ] - result = subprocess.run( - [str(self.binary)], - input="".join(json.dumps(line) + "\n" for line in lines), - capture_output=True, text=True, timeout=10, env={"PATH": "/usr/bin:/bin"}) - self.assertEqual(result.returncode, 0) - # Nothing but protocol lines on stdout, and nothing before `ready` - # except the pong the host asked for. - out = [json.loads(line) for line in result.stdout.splitlines()] - self.assertEqual(out, [{"type": "pong", "id": 17}]) - - def test_it_exits_when_the_host_closes_stdin(self): - result = subprocess.run([str(self.binary)], input="", capture_output=True, - text=True, timeout=10, env={"PATH": "/usr/bin:/bin"}) - self.assertEqual(result.returncode, 0) - self.assertEqual(result.stdout, "") - - -class Launcher(unittest.TestCase): - - def test_without_swiftc_it_fails_with_a_reason_and_prints_nothing(self): - # A copy with no build in it, and a PATH with nothing on it, so the - # launcher has to build and can't. The supervisor marks it broken; what - # matters here is that stdout stays empty, since the host would read - # anything there as a protocol line. - with tempfile.TemporaryDirectory() as scratch: - copy = pathlib.Path(scratch) / "away" - copy.mkdir() - for name in ("run", "away.swift", "manifest.json"): - shutil.copy2(HERE / name, copy / name) - empty = pathlib.Path(scratch) / "empty-path" - empty.mkdir() - result = subprocess.run(["/bin/bash", str(copy / "run")], cwd=copy, - capture_output=True, text=True, timeout=10, - env={"PATH": str(empty)}) - self.assertNotEqual(result.returncode, 0) - self.assertEqual(result.stdout, "") - self.assertIn("swiftc", result.stderr) - self.assertFalse((copy / ".build" / "away").exists()) - - def test_it_clears_a_build_a_killed_start_left_behind(self): - # A start the host killed mid-compile leaves .build/away.. The - # next start removes those whose process is gone, and leaves alone - # one still being written by a start that's running. - with tempfile.TemporaryDirectory() as scratch: - copy = pathlib.Path(scratch) / "away" - (copy / ".build").mkdir(parents=True) - for name in ("run", "away.swift", "manifest.json"): - shutil.copy2(HERE / name, copy / name) - gone = subprocess.Popen(["/bin/sh", "-c", "exit 0"]) - gone.wait() - (copy / ".build" / ("away.%d" % gone.pid)).write_text("partial") - (copy / ".build" / ("away.%d" % os.getpid())).write_text("in progress") - # /bin has rm but no swiftc, so it clears up and then can't build. - subprocess.run(["/bin/bash", str(copy / "run")], cwd=copy, - capture_output=True, text=True, timeout=10, - env={"PATH": "/bin"}) - self.assertFalse((copy / ".build" / ("away.%d" % gone.pid)).exists()) - self.assertTrue((copy / ".build" / ("away.%d" % os.getpid())).exists()) - - -class Manifest(unittest.TestCase): - - def setUp(self): - with open(HERE / "manifest.json") as fh: - self.manifest = json.load(fh) - - def test_it_is_a_service_asking_only_for_what_it_uses(self): - self.assertEqual(self.manifest["schema"], 2) - self.assertEqual(self.manifest["mode"], "service") - self.assertEqual(sorted(self.manifest["capabilities"]), ["bluetooth", "signal:presence"]) - - def test_it_asks_for_a_handshake_long_enough_to_compile(self): - # A cold swiftc -O took 15 s on an Apple Silicon Mac; the host's usual - # 10 s would kill every fresh install's first start. - self.assertGreaterEqual(self.manifest["handshakeSeconds"], 60) - self.assertLessEqual(self.manifest["handshakeSeconds"], 120) - - def test_it_lives_in_settings_with_typed_config(self): - # Set and forget, so a Settings page rather than a tab, and its keys - # are controls: the phone from what the service offers, the two waits - # from fixed lists that keep the silence above the 75 s an idle phone - # was measured going quiet. - self.assertEqual(self.manifest["surfaces"], ["settings"]) - kinds = {entry["key"]: entry for entry in self.manifest["config"]} - self.assertEqual(kinds["STACKNUDGE_EXT_AWAY_PHONE"]["type"], "dynamic") - idle, silence = kinds["STACKNUDGE_EXT_AWAY_IDLE"], kinds["STACKNUDGE_EXT_AWAY_SILENCE"] - self.assertEqual((idle["type"], idle["unit"]), ("number", "seconds")) - self.assertIn(idle["default"], idle["options"]) - self.assertIn(silence["default"], silence["options"]) - self.assertGreaterEqual(min(silence["options"]), 90) - - def test_its_config_keys_are_the_ones_the_program_reads(self): - keys = [entry["key"] for entry in self.manifest["config"]] - self.assertEqual(keys, ["STACKNUDGE_EXT_AWAY_PHONE", "STACKNUDGE_EXT_AWAY_IDLE", - "STACKNUDGE_EXT_AWAY_SILENCE"]) - source = (HERE / "away.swift").read_text() - for key in keys: - self.assertIn('"%s"' % key, source) - - def test_its_tier_is_recorded_for_review(self): - # Away can't do its job below `trusted`: bluetooth and presence are - # both trusted capabilities. The tier lives in the reviewer-owned - # extensions/tiers.json rather than here, so it can't promote itself. - tiers_path = HERE.parent / "tiers.json" - if not tiers_path.exists(): - self.skipTest("not in a checkout of the extensions repository") - with open(tiers_path) as fh: - self.assertEqual(json.load(fh).get("away"), "trusted") - - -if __name__ == "__main__": - unittest.main() diff --git a/extensions/derby/manifest.json b/extensions/derby/manifest.json deleted file mode 100644 index 8866ba4..0000000 --- a/extensions/derby/manifest.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "id": "derby", - "name": "Token Derby", - "description": "A horse race where each runner advances on the tokens its owner burns.", - "version": "1.1.0", - "schema": 1, - "tab": { - "label": "Derby" - }, - "run": "./run", - "requires": [ - "python3" - ], - "config": [ - { - "key": "STACKNUDGE_EXT_DERBY_ORG", - "label": "Organisation", - "help": "Whose races to show, exactly as spelled \u2014 the name is case-sensitive.", - "placeholder": "StackOne" - }, - { - "key": "STACKNUDGE_EXT_DERBY_BASE", - "label": "API base", - "help": "Leave blank for the public instance. https:// only.", - "placeholder": "https://token-derby.mauricode.co.uk/api" - } - ], - "refresh": { - "onOpen": true, - "intervalSeconds": 30, - "whileFocusedOnly": true - } -} diff --git a/extensions/derby/run b/extensions/derby/run deleted file mode 100755 index d039e25..0000000 --- a/extensions/derby/run +++ /dev/null @@ -1,642 +0,0 @@ -#!/usr/bin/env python3 -"""The Token Derby: a horse race where each runner advances on the tokens its -owner burns. - -Read-only against a third-party service (token-derby.mauricode.co.uk); nothing -about this machine is sent. Colour clamping, sprite geometry and the polling -schedule are the host's — declared in manifest.json, not here. - -Python rather than /bin/sh because this parses JSON from the network, and the -shell version would have wanted awk for it. Awk taking program text built from -a server's response is how this repo's packaging script acquired an -arbitrary-code-execution bug. - -See docs/extensions.md for the schema this prints. -""" - -import json -import math -import os -import sys -import time -import urllib.error -import urllib.parse -import urllib.request -from datetime import datetime, timezone - -DEFAULT_BASE = "https://token-derby.mauricode.co.uk/api" -ORG_KEY = "STACKNUDGE_EXT_DERBY_ORG" -BASE_KEY = "STACKNUDGE_EXT_DERBY_BASE" -# One budget across both hops rather than a timeout on each, because the two -# are not the same size: the race list measures 2-4s and the race itself under -# one, and a fixed per-request limit has to be big enough for the slow one -# while leaving room for both inside the host's 12s. Splitting it evenly meant -# the slow hop had a 5s ceiling it occasionally hit, and a hop that times out -# fails the whole fetch. -# -# The deadline is enforced by this script, not by the socket. urlopen's -# `timeout` is a per-operation *idle* limit, not a total one: a server that -# dribbles a response keeps the socket busy and never trips it. Measured — -# urlopen(timeout=1.5) against a server writing a byte a second returned after -# 8s without raising. So the budget is checked before each hop and between -# reads, and the socket timeout is left to do the one job it is good at, which -# is noticing that nothing is arriving at all. -TOTAL_BUDGET = 9 -MAX_PER_REQUEST = 6 -READ_CHUNK = 65536 -# The host stops reading at 8MB; there is no reason for this script to hold -# more than a race document before it gives up. -MAX_BODY_BYTES = 4 * 1024 * 1024 - -# A horse, 16x11. "H" is the coat, "M" the mane and tail, "." transparent. At -# 1.5pt a cell the silhouette carries it, so the legs gather and splay rather -# than articulate. -HORSE_STANDING = [ - "...........HHHH.", - "..........MHHHHH", - ".........MMHH...", - "M.......MMH.....", - "MMM...HHHHH.....", - ".MMHHHHHHHH.....", - "..MHHHHHHHH.....", - "...HHHHHHH......", - "...H.H..H.H.....", - "...H.H..H.H.....", - "...H.H..H.H.....", -] -HORSE_EXTENDED = HORSE_STANDING[:8] + [ - "..H...H.H...H...", - "..H...H.H...H...", - "..H...H.H...H...", -] - -# The finish line: a two-cell chequer, anchored at the trailing edge so it sits -# at the end of the track whatever the fill is doing. Eleven rows to stand as -# tall as the horse, so the post reads as a post rather than a dash. -# -# "W" and "K" rather than the coat's keys: a palette is per-ornament, so these -# stay fixed while every horse's silks differ. -FINISH_POST = [ - "WK" if row % 2 == 0 else "KW" - for row in range(11) -] -FINISH_PALETTE = {"W": "#FFFFFF", "K": "#111111"} - -# Anything the service doesn't give a colour for. The host clamps whatever it -# is handed toward legibility against the current appearance, so this only has -# to be roughly right rather than correct in both modes. -DEFAULT_COAT = "#7FD1B9" - - -# --- Formatting ------------------------------------------------------------- -# Both mirror a Swift helper in panel/Formatting.swift (TokenFormat.short, -# QuotaReset.shortLabel). An extension can't reach them, and a Derby row that -# abbreviates differently from the Usage tab beside it reads as two apps. - -def short_tokens(count): - """1234567 -> "1.2M", 218000 -> "218K", 42 -> "42". - - The K branch rounds half away from zero to match Swift's Double.rounded(). - Python's round() is half-to-even, which made 2500 "2K" here and "3K" there. - """ - count = int(count) - if count >= 1_000_000: - return "%.1fM" % (count / 1_000_000) - if count >= 1_000: - return "%dK" % int(count / 1_000 + 0.5) - return str(count) - - -def short_countdown(seconds): - """Seconds remaining as "2d3h" / "5h44m" / "12m".""" - seconds = int(seconds) - if seconds <= 0: - return None - if seconds >= 86400: - days, hours = seconds // 86400, (seconds % 86400) // 3600 - return "%dd%dh" % (days, hours) if hours else "%dd" % days - if seconds >= 3600: - hours, minutes = seconds // 3600, (seconds % 3600) // 60 - return "%dh%dm" % (hours, minutes) if minutes else "%dh" % hours - # Sub-minute is genuinely about to end, and "0m" reads as a stopped clock. - return "%dm" % max(1, seconds // 60) - - -# --- Colour ----------------------------------------------------------------- - -def mane_for(hex_color, fraction=0.45): - """The mane and tail, shaded from the coat so the silhouette has an edge. - - Darker, except on a coat too dark to darken: #000000 shaded toward black is - still #000000, and the field has real black horses in it. Those lighten - instead. All that matters is that the two differ. - """ - parsed = parse_hex(hex_color) - if parsed is None: - return hex_color - if max(parsed) < 64: - lifted = tuple(min(255, int(round(c + (255 - c) * fraction))) for c in parsed) - return "#%02X%02X%02X" % lifted - keep = 1 - fraction - return "#%02X%02X%02X" % tuple(int(round(c * keep)) for c in parsed) - - -def parse_hex(value): - """"#RGB", "#RRGGBB" or either without the hash -> (r, g, b), else None. - - More tolerant than the host, which requires the hash. Read loosely, write - strictly: everything emitted goes through normalise_hex, so a horse doesn't - lose its silks to a punctuation difference. - """ - if not isinstance(value, str): - return None - text = value.strip().lstrip("#") - if len(text) == 3: - text = "".join(c * 2 for c in text) - if len(text) != 6: - return None - try: - return tuple(int(text[i:i + 2], 16) for i in (0, 2, 4)) - except ValueError: - return None - - -def normalise_hex(value): - """A colour in the exact form the host accepts, or None.""" - parsed = parse_hex(value) - return None if parsed is None else "#%02X%02X%02X" % parsed - - -# --- The race --------------------------------------------------------------- - -def parse_time(value): - """An ISO 8601 stamp. The service sends milliseconds and a trailing "Z", - which datetime.fromisoformat refused before 3.11.""" - if not isinstance(value, str) or not value: - return None - text = value.strip() - if text.endswith("Z"): - text = text[:-1] + "+00:00" - try: - parsed = datetime.fromisoformat(text) - except ValueError: - return None - return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc) - - -def duration_seconds(start, end): - """How long the race runs, or None if either end is unreadable.""" - first, last = parse_time(start), parse_time(end) - if first is None or last is None: - return None - seconds = (last - first).total_seconds() - return seconds if seconds > 0 else None - - -def number(value, default=0.0): - """A token count, whatever shape the API sent it in. - - Ints and floats both arrive. A bool is an int in Python and is not a count. - Non-finite is refused because json.loads accepts bare Infinity/NaN, int(inf) - raises rather than returning something wrong, and a NaN serialises back out - as a bare NaN token the host's decoder rejects. - """ - if isinstance(value, bool) or not isinstance(value, (int, float)): - return default - return float(value) if math.isfinite(value) else default - - -def pick(races): - """The race worth showing, by the same rule the derby's own site uses. - - Newest live, else newest finished, else the *soonest* pending — that last - one sorts the other way because a race that hasn't started is interesting - for being next rather than recent. Matching the site matters: picking a - different race from the page this mirrors would read as stale data. - - One divergence: the site sorts on `new Date(start_time)`, so an unreadable - stamp compares equal to everything and keeps its position; here it sorts as - the epoch. Both are arbitrary, and reproducing a NaN comparator to match a - tie-break nobody relies on is not worth the code. - """ - usable = [r for r in races if isinstance(r, dict) and r.get("join_code")] - - def started(race): - when = parse_time(race.get("start_time")) - return when.timestamp() if when else 0.0 - - for status, newest_first in (("live", True), ("finished", True), ("pending", False)): - matching = sorted([r for r in usable if r.get("status") == status], - key=started, reverse=newest_first) - if matching: - return matching[0] - return None - - -def elapsed_fraction(race): - """How much of the race has run, 0...1. - - A finished race is fully run whatever the clock says; a pending one hasn't - started, so the field is still at the gate. - """ - status = race.get("status") - if status == "finished": - return 1.0 - if status != "live": - return 0.0 - total = duration_seconds(race.get("start_time"), race.get("end_time")) - left = race.get("time_left_seconds") - if not total or not isinstance(left, (int, float)) or isinstance(left, bool): - return 0.0 - return min(1.0, max(0.0, 1 - float(left) / total)) - - -def position(tokens, leader, elapsed): - """Where a horse sits on the track. - - Scaled by elapsed time as well as by the leader. Leader-relative alone pins - the front-runner to the finish line from the first minute, making a - twelve-hour race look permanently over. - """ - if leader <= 0: - return 0.0 - return (tokens / leader) * elapsed - - -def scored(horse): - """What the race is ranked on, and therefore what the bar draws. - - Drawing current_tokens put a 4th-placed horse's bar ahead of 2nd's — the - league discounts raw usage. Absent on a race that isn't scoring, so it - falls back rather than drawing nothing. - """ - raw = number(horse.get("current_tokens")) - return number(horse.get("scored_tokens"), raw) - - -# --- The document ----------------------------------------------------------- - -def row_id(entry): - """The row's id, or None when there isn't one. - - `is None` rather than truthiness, and derived once so the dedupe key and - the emitted id can't differ. horse_id 0 is falsy and is still an id: - dropping it cost its row *and* promoted the next horse to the finish line, - since the leader is a max over whatever survived. - """ - raw = entry.get("horse_id") - if raw is None: - return None - return str(raw).strip() or None - - -def text(value): - """A string field, trimmed, or "" if there is nothing in it. - - The host drops a row whose title comes out blank, so "present but only - spaces" is resolved here rather than left for it to discover. - """ - return str(value).strip() if isinstance(value, str) else "" - - -def division_of(horse, names): - """`division` is 1-based into league_division_names.""" - index = horse.get("division") - if not isinstance(index, int) or isinstance(index, bool): - return None - if 1 <= index <= len(names) and isinstance(names[index - 1], str): - return names[index - 1] - return None - - -def footnote_for(horse, names): - pace = number(horse.get("pace_15m")) - division = division_of(horse, names) - parts = [] - if pace > 0: - parts.append("%s/15m" % short_tokens(pace)) - if division: - parts.append(division) - return " · ".join(parts) - - -def ornament_for(coat, animated): - """A still horse gets one frame and no fps, so the host starts no timeline.""" - frames = [HORSE_STANDING, HORSE_EXTENDED] if animated else [HORSE_STANDING] - return { - "kind": "sprite", - "fps": 7 if animated else 0, - "anchor": "fill-edge", - "palette": {"H": coat, "M": mane_for(coat)}, - "frames": frames, - } - - -def finish_line(): - """The post at the end of the track. Still, and anchored trailing, so it - stays put while the horse rides the fill.""" - return { - "kind": "sprite", - "fps": 0, - "anchor": "trailing", - "palette": FINISH_PALETTE, - "frames": [FINISH_POST], - } - - -def row_for(identifier, horse, leader, elapsed, live, names): - colours = horse.get("colors") - coat = normalise_hex(colours.get("body") if isinstance(colours, dict) else None) - if coat is None: - coat = DEFAULT_COAT - tokens = scored(horse) - rank = horse.get("rank") - pace = number(horse.get("pace_15m")) - return { - "id": identifier, - # An en dash rather than a blank, so an unranked horse still lines its - # name up with the ranked ones above it. - "lead": str(rank) if isinstance(rank, int) and not isinstance(rank, bool) else "–", - # Stripped before the fallback, not just tested for falsiness. The host - # trims every text field and drops a row whose title comes out empty — - # so a horse named " " cost its whole row, rank and bar included, - # rather than just its name. - "title": text(horse.get("name")) or "Unnamed", - "subtitle": text(horse.get("user_name")), - "value": short_tokens(tokens), - "footnote": footnote_for(horse, names), - "track": {"fill": position(tokens, leader, elapsed), "tint": coat}, - # The post first so the horse draws over it at the line, then the - # horse. Only a live runner burning tokens animates — a finished race - # is a standings table. - "ornaments": [finish_line(), ornament_for(coat, live and pace > 0)], - } - - -def document(race): - """One race as a view document.""" - # Deduplicated here rather than left to the host, which drops the second of - # a duplicate pair without saying so. The id is what an action names a row - # by, so two rows answering to one id is a row that acts on the wrong horse. - horses = [] - seen_ids = set() - for entry in race.get("horses") or []: - if not isinstance(entry, dict): - continue - identifier = row_id(entry) - if identifier is None or identifier in seen_ids: - continue - seen_ids.add(identifier) - horses.append((identifier, entry)) - names = [n for n in race.get("league_division_names") or [] if isinstance(n, str)] - status = str(race.get("status") or "") - live = status == "live" - elapsed = elapsed_fraction(race) - leader = max([scored(h) for _, h in horses], default=0.0) - - header = { - "title": str(race.get("name") or "Race"), - "badge": {"text": status.upper() or "UNKNOWN", - "tone": {"live": "success", "pending": "warning"}.get(status, "neutral")}, - } - if live: - left = race.get("time_left_seconds") - if isinstance(left, (int, float)) and not isinstance(left, bool): - countdown = short_countdown(left) - if countdown: - header["trailing"] = countdown - - return { - "schema": 1, - "state": "ok" if horses else "empty", - "message": None if horses else "No runners in this race yet.", - "header": header, - # Server order is the ranking; re-sorting here risks disagreeing with it. - "rows": [row_for(i, h, leader, elapsed, live, names) for i, h in horses], - "actions": [{"id": "refresh", "label": "Sync now", "key": "r"}], - } - - -def message(state, text): - return {"schema": 1, "state": state, "message": text, - "actions": [{"id": "refresh", "label": "Sync now", "key": "r"}]} - - -# --- I/O -------------------------------------------------------------------- - -def valid_base(value): - """https only, and no credentials in the URL. - - The value comes from the config file, which is the user's own, so this is - not a trust boundary — but a base silently downgraded to http would send a - request the user thinks is encrypted, and that is worth refusing loudly. - """ - if not value: - return DEFAULT_BASE - parsed = urllib.parse.urlsplit(value) - if parsed.scheme != "https" or not parsed.netloc: - return None - # Both halves: urlsplit gives username "" for a ":pw@host" userinfo, and "" - # is falsy, so checking the username alone let a password-only credential - # through. - if parsed.username or parsed.password: - return None - return value.rstrip("/") - - -class NotJSON(Exception): - """The request succeeded and returned something that isn't data. - - The derby is a single-page app behind a CDN: a request it doesn't recognise - gets the app's own index.html and a 200 rather than a 404, so a mistyped - organisation looks exactly like a corrupt response. - """ - - -class UnknownOrg(Exception): - """No organisation by that name. - - Its own type because the name is case-sensitive and nothing about the - failure says so: "StackOne" works, "stackone" gets the web page. - """ - - -def _refuse_constant(literal): - """json.loads accepts Infinity / -Infinity / NaN by default. None of them is - a number this document can carry, and letting them in only moves the failure - somewhere less legible.""" - raise ValueError("unexpected %s in the response" % literal) - - -class NoDowngrade(urllib.request.HTTPRedirectHandler): - """Refuse a redirect that leaves https. - - valid_base() checks the URL we type; urllib follows redirects and Python's - stock handler will send you from https to http. The settings field promises - only https addresses, so the promise should survive a hop. No credentials - ride on these requests — this is about the claim being true. - """ - - def redirect_request(self, req, fp, code, msg, headers, newurl): - if urllib.parse.urlsplit(newurl).scheme != "https": - raise urllib.error.URLError("refused a redirect off https") - return super().redirect_request(req, fp, code, msg, headers, newurl) - - -_opener = urllib.request.build_opener(NoDowngrade()) - - -def remaining(deadline): - """Idle allowance for the next socket operation. - - Raises rather than returning a floor when the budget is spent: granting a - last second to a hop that is already over the deadline is how two hops end - up past the host's limit, which is the thing the budget exists to stop. - """ - left = deadline - time.monotonic() - if left <= 0: - raise TimeoutError("the derby ran out of time") - return min(float(MAX_PER_REQUEST), left) - - -def read_within(response, deadline): - """The body, giving up if the budget runs out mid-read. - - A slow-but-steady response never trips the socket timeout, so this is the - only thing bounding how long a single hop can take. - """ - chunks, total = [], 0 - while True: - if time.monotonic() > deadline: - raise TimeoutError("the derby ran out of time") - # read1, not read: read(n) blocks until it has n bytes or hits EOF, so - # a dribbling response never returns control and the check above never - # runs. Measured — it capped a 1-byte-a-second stream at 20s against a - # 4s deadline. read1 returns what one underlying read produced. - chunk = response.read1(READ_CHUNK) - if not chunk: - break - total += len(chunk) - if total > MAX_BODY_BYTES: - raise ValueError("the derby sent more than this reads") - chunks.append(chunk) - return b"".join(chunks).decode("utf-8", errors="replace") - - -def get_json(url, deadline): - request = urllib.request.Request( - url, headers={"User-Agent": "stack-nudge", "Accept": "application/json"}) - with _opener.open(request, timeout=remaining(deadline)) as response: - content_type = (response.headers.get("Content-Type") or "").lower() - body = read_within(response, deadline) - if "json" not in content_type: - raise NotJSON(content_type or "no content type") - return json.loads(body, parse_constant=_refuse_constant) - - -def api_error_code(error): - """The derby answers a failed call with {"code": ..., "message": ...}.""" - try: - payload = json.loads(error.read().decode("utf-8", errors="replace")) - except (ValueError, OSError): - return None, None - if not isinstance(payload, dict): - return None, None - return payload.get("code"), payload.get("message") - - -def fetch(base, org, deadline): - """Two hops: the org's races, then the one worth showing.""" - try: - listing = get_json( - "%s/organisations/%s/races" % (base, urllib.parse.quote(org, safe="")), deadline) - except NotJSON: - # The web page came back instead of data. On this route that means the - # organisation isn't one, rather than anything being broken. - raise UnknownOrg(org) from None - except urllib.error.HTTPError as error: - # Only a 404 on *this* hop is about the organisation. The race list is - # re-read every 30s, so a race deleted between the two hops 404s the - # second one — and blaming the org there sends someone to correct a - # setting that was right. - if error.code == 404: - raise UnknownOrg(org) from None - raise - races = listing.get("races") if isinstance(listing, dict) else None - chosen = pick(races or []) - if not chosen: - return None - code = urllib.parse.quote(str(chosen["join_code"]), safe="") - race = get_json("%s/races/%s" % (base, code), deadline) - return race if isinstance(race, dict) else None - - -def build(): - org = (os.environ.get(ORG_KEY) or "").strip() - if not org: - return message("empty", - "Set an organisation in Settings → Extensions → Token Derby.") - - base = valid_base((os.environ.get(BASE_KEY) or "").strip()) - if base is None: - return message("error", "The API base must be an https:// URL.") - - try: - race = fetch(base, org, time.monotonic() + TOTAL_BUDGET) - except UnknownOrg: - # Worth spelling out: the name is case-sensitive, "StackOne" works and - # "stackone" does not, and nothing about the failure would tell you. - return message("empty", - 'No organisation named "%s". The name is case-sensitive.' % org) - except NotJSON: - return message("error", "The derby answered with a web page instead of data.") - except urllib.error.HTTPError as error: - code, detail = api_error_code(error) - if code == "ORG_NOT_FOUND": - return message("empty", 'No organisation named "%s".' % org) - if code == "UNAUTHENTICATED": - return message("error", "This organisation's races aren't public.") - # A bare 404 here is the *race* hop — the org hop raises UnknownOrg — - # which means the race went away between reading the list and reading - # it. The next poll picks up whatever replaced it. - if error.code == 404: - return message("empty", "That race has gone. Checking again shortly.") - # Only if it is a string. The field is the service's, and a non-string - # there put a JSON object where the host's decoder wants a string — - # which fails the *whole* document, so the pane says "wrong type for - # message" rather than showing the API's error. - detail = detail if isinstance(detail, str) and detail else None - return message("error", detail or "The derby returned %d." % error.code) - except urllib.error.URLError as error: - return message("error", "Couldn't reach the derby — %s." % error.reason) - except TimeoutError: - return message("error", "The derby took too long to answer.") - except ValueError: - return message("error", "The derby's response wasn't readable.") - except OSError as error: - return message("error", "Couldn't reach the derby — %s." % error) - - if not race: - return message("empty", 'No races found for "%s".' % org) - - # Inside its own guard, not outside the fetch's. Building the document was - # the one step whose failures escaped as a traceback — the host reads that - # as a crashed extension rather than as the extension reporting something, - # and the pane says nothing useful. - try: - return document(race) - except (ValueError, TypeError, OverflowError, KeyError, IndexError): - return message("error", "The derby sent a race this version can't read.") - - -def main(): - # Actions are the host re-running us with flags. There is only one, and its - # answer is a fresh document — which is what an argument-free run prints - # anyway, so nothing here needs to branch on argv. - json.dump(build(), sys.stdout) - sys.stdout.write("\n") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/extensions/derby/test_derby.py b/extensions/derby/test_derby.py deleted file mode 100644 index fda93b3..0000000 --- a/extensions/derby/test_derby.py +++ /dev/null @@ -1,857 +0,0 @@ -#!/usr/bin/env python3 -"""Tests for the Token Derby extension. - -Run them with `python3 -m unittest discover extensions`, which is what CI does. - -They ship inside the package on purpose. This and `system` are the two -extensions people read when writing their own, and "how do I test one of -these?" is a question the reference should answer rather than leave to taste. - -Everything here is offline. The two functions that touch the network are the -two that aren't tested; everything they hand off to is pure and is. -""" - -import importlib.machinery -import importlib.util -import json -import pathlib -import unittest - -# The executable has no .py extension — the host runs it by path, not by -# import — so it is loaded explicitly rather than found on sys.path. -_PATH = pathlib.Path(__file__).with_name("run") -_LOADER = importlib.machinery.SourceFileLoader("derby_run", str(_PATH)) -_SPEC = importlib.util.spec_from_loader(_LOADER.name, _LOADER) -derby = importlib.util.module_from_spec(_SPEC) -_LOADER.exec_module(derby) - - -class _Forbidden: - """The opener every test starts with. - - The two functions that touch the network are stubbed where they are - tested, but nothing made that true — patching the wrong seam once let the - whole suite quietly start making live requests against a real service, and - the only symptom was that it took five seconds instead of two - milliseconds. Now reaching the network is a failure with the URL in it. - """ - - def open(self, request, timeout=None): - raise AssertionError("a test reached the network: %s" % request.full_url) - - -def setUpModule(): - derby._opener = _Forbidden() - - -class Formatting(unittest.TestCase): - """Both mirror a Swift helper the panel uses for its own tabs. A Derby row - that abbreviated differently from the Usage tab beside it would read as two - apps sharing one panel.""" - - def test_token_counts_abbreviate_like_the_panel_does(self): - self.assertEqual(derby.short_tokens(42), "42") - self.assertEqual(derby.short_tokens(999), "999") - self.assertEqual(derby.short_tokens(1000), "1K") - self.assertEqual(derby.short_tokens(218_000), "218K") - self.assertEqual(derby.short_tokens(1_250_000), "1.2M") - # A half-token double is a real value from this API, not a typo. - self.assertEqual(derby.short_tokens(1500.5), "2K") - - # Half rounds *away from zero*, matching Swift's Double.rounded(). Python's - # round() is half-to-even, so every x500 with an even thousands part - # disagreed — and 1500, the only boundary the first version of this test - # checked, is the one where the two happen to agree. - def test_the_K_branch_rounds_half_away_from_zero(self): - self.assertEqual(derby.short_tokens(2500), "3K") - self.assertEqual(derby.short_tokens(4500), "5K") - self.assertEqual(derby.short_tokens(6500), "7K") - self.assertEqual(derby.short_tokens(1500), "2K") - self.assertEqual(derby.short_tokens(3500), "4K") - - def test_countdowns_abbreviate_like_the_panel_does(self): - self.assertEqual(derby.short_countdown(20_700), "5h45m") - self.assertEqual(derby.short_countdown(7200), "2h") - self.assertEqual(derby.short_countdown(180_000), "2d2h") - self.assertEqual(derby.short_countdown(172_800), "2d") - self.assertEqual(derby.short_countdown(720), "12m") - - def test_a_countdown_that_has_run_out_is_absent_rather_than_zero(self): - # "0m" reads as a stopped clock; sub-minute is genuinely about to end. - self.assertEqual(derby.short_countdown(30), "1m") - self.assertIsNone(derby.short_countdown(0)) - self.assertIsNone(derby.short_countdown(-5)) - - -class Budget(unittest.TestCase): - - # The whole fetch has to finish inside the host's 12s or it is killed before - # it can print its own error document — a slow service then looks like a - # crashed extension. - def test_the_whole_fetch_fits_the_hosts_budget(self): - self.assertLess(derby.TOTAL_BUDGET, 12) - - # One budget shared across both hops, not a ceiling on each. The two are - # different sizes — the race list measures 2-4s, the race itself under one — - # so an even split gave the slow hop a limit it occasionally hit while the - # fast one left most of its share unused. - def test_a_slow_first_hop_can_use_more_than_its_half(self): - self.assertGreater(derby.MAX_PER_REQUEST, derby.TOTAL_BUDGET / 2) - - def test_what_is_left_of_the_budget_shrinks_as_it_is_spent(self): - now = derby.time.monotonic() - self.assertAlmostEqual(derby.remaining(now + 4), 4, delta=0.1) - # Capped, so one hop cannot take the lot. - self.assertEqual(derby.remaining(now + 99), derby.MAX_PER_REQUEST) - - -class Colour(unittest.TestCase): - - def test_hex_parsing_accepts_both_lengths(self): - self.assertEqual(derby.parse_hex("#ff0000"), (255, 0, 0)) - self.assertEqual(derby.parse_hex("#f00"), (255, 0, 0)) - self.assertEqual(derby.parse_hex(" #AbCdEf "), (0xAB, 0xCD, 0xEF)) - - def test_hex_parsing_rejects_everything_else(self): - for raw in ["red", "#ff00", "#gggggg", "#", "", None, 7, []]: - self.assertIsNone(derby.parse_hex(raw), raw) - - # Read loosely, write strictly. The host requires the hash and drops a bare - # "ff0000" back to the accent colour, so a horse whose silks arrived - # without one would quietly lose them. - def test_a_colour_without_its_hash_is_read_and_then_written_back_with_one(self): - self.assertEqual(derby.parse_hex("ff0000"), (255, 0, 0)) - self.assertEqual(derby.normalise_hex("ff0000"), "#FF0000") - self.assertEqual(derby.normalise_hex("#f00"), "#FF0000") - self.assertIsNone(derby.normalise_hex("red")) - - def test_the_mane_is_darker_than_the_coat(self): - # Without this the mane is the same colour as the body and the horse is - # a blob at 1.5pt a cell. - self.assertEqual(derby.mane_for("#FFFFFF"), "#8C8C8C") - - # The field has real black horses in it, and #000000 shaded toward black is - # still #000000 — which drew them as flat silhouettes with no mane. - def test_a_coat_too_dark_to_darken_gets_a_lighter_mane_instead(self): - self.assertNotEqual(derby.mane_for("#000000"), "#000000") - self.assertEqual(derby.mane_for("#000000"), "#737373") - for coat in ["#000000", "#101010", "#1A0A0A"]: - self.assertNotEqual(derby.mane_for(coat), coat, coat) - - def test_shading_something_unparseable_leaves_it_alone(self): - self.assertEqual(derby.mane_for("nonsense"), "nonsense") - - -class Numbers(unittest.TestCase): - - def test_token_counts_arrive_as_both_ints_and_floats(self): - self.assertEqual(derby.number(5), 5.0) - self.assertEqual(derby.number(5.5), 5.5) - - def test_a_missing_or_wrong_typed_count_falls_back(self): - self.assertEqual(derby.number(None), 0.0) - self.assertEqual(derby.number("12"), 0.0) - self.assertEqual(derby.number(None, 3.0), 3.0) - - # json.loads accepts the bare literals Infinity, -Infinity and NaN, and - # int(inf) raises rather than returning something wrong — so a server - # sending one crashed the script instead of producing a document. A NaN - # would also serialise back out as a bare NaN token, which the host's - # JSONDecoder rejects. - def test_a_non_finite_number_is_not_a_token_count(self): - for value in [float("inf"), float("-inf"), float("nan")]: - self.assertEqual(derby.number(value), 0.0, value) - - def test_a_bool_is_not_a_token_count(self): - # True == 1 in Python, so a sloppy isinstance check draws a bar for it. - self.assertEqual(derby.number(True), 0.0) - self.assertEqual(derby.number(False), 0.0) - - -class Timestamps(unittest.TestCase): - - def test_the_services_own_stamp_parses(self): - # It stamps milliseconds and a trailing Z. - parsed = derby.parse_time("2026-09-18T08:00:00.000Z") - self.assertIsNotNone(parsed) - self.assertEqual(parsed.year, 2026) - - def test_a_stamp_without_fractional_seconds_parses_too(self): - self.assertIsNotNone(derby.parse_time("2026-09-18T08:00:00Z")) - self.assertIsNotNone(derby.parse_time("2026-09-18T08:00:00+00:00")) - - def test_an_unreadable_stamp_is_none_rather_than_a_crash(self): - for raw in ["", None, "yesterday", "2026-13-45T99:99:99Z", 7]: - self.assertIsNone(derby.parse_time(raw), raw) - - def test_duration_needs_both_ends_and_a_forward_direction(self): - start, end = "2026-09-18T08:00:00Z", "2026-09-18T20:00:00Z" - self.assertEqual(derby.duration_seconds(start, end), 43200) - self.assertIsNone(derby.duration_seconds(end, start)) - self.assertIsNone(derby.duration_seconds(start, start)) - self.assertIsNone(derby.duration_seconds(start, None)) - - -def race(status="live", **extra): - base = { - "join_code": "ABC", - "name": "StackOne Token League", - "status": status, - "start_time": "2026-09-18T08:00:00.000Z", - "end_time": "2026-09-18T20:00:00.000Z", - "time_left_seconds": 21600, - "league_division_names": ["Premier Division", "Second Division"], - "horses": [], - } - base.update(extra) - return base - - -def runner_of(row): - """The horse in a row's ornament list. - - Rows carry two now — the finish post anchored trailing, then the runner - anchored fill-edge — so a test about the horse has to say which it means - rather than taking the first one it finds. - """ - return next(o for o in row["ornaments"] if o["anchor"] == "fill-edge") - - -def post_of(row): - return next(o for o in row["ornaments"] if o["anchor"] == "trailing") - - -def horse(id="h1", **extra): - base = {"horse_id": id, "name": "black & white", "user_name": "Yashika", - "rank": 1, "current_tokens": 1000, "scored_tokens": 900, - "pace_15m": 36000, "division": 1, "colors": {"body": "#FFFFFF"}} - base.update(extra) - return base - - -class Picking(unittest.TestCase): - """The same rule the derby's own site uses. An extension that picked a - different race from the page it mirrors would read as stale data.""" - - def test_a_live_race_wins(self): - chosen = derby.pick([race("finished", join_code="OLD"), race("live", join_code="NOW")]) - self.assertEqual(chosen["join_code"], "NOW") - - def test_the_newest_live_race_wins(self): - chosen = derby.pick([ - race("live", join_code="OLD", start_time="2026-09-01T08:00:00Z"), - race("live", join_code="NEW", start_time="2026-09-18T08:00:00Z"), - ]) - self.assertEqual(chosen["join_code"], "NEW") - - def test_with_nothing_live_the_most_recent_finish_wins(self): - chosen = derby.pick([ - race("finished", join_code="OLD", start_time="2026-09-01T08:00:00Z"), - race("finished", join_code="RECENT", start_time="2026-09-17T08:00:00Z"), - race("pending", join_code="SOON", start_time="2026-09-19T08:00:00Z"), - ]) - self.assertEqual(chosen["join_code"], "RECENT") - - def test_pending_races_sort_the_other_way(self): - # A race that hasn't started is interesting for being next, not recent. - chosen = derby.pick([ - race("pending", join_code="LATER", start_time="2026-10-01T08:00:00Z"), - race("pending", join_code="SOON", start_time="2026-09-19T08:00:00Z"), - ]) - self.assertEqual(chosen["join_code"], "SOON") - - def test_an_entry_without_a_join_code_is_not_a_race(self): - self.assertIsNone(derby.pick([{"status": "live"}, "nonsense", None])) - self.assertIsNone(derby.pick([])) - - -class Track(unittest.TestCase): - - def test_a_finished_race_is_fully_run_whatever_the_clock_says(self): - self.assertEqual(derby.elapsed_fraction(race("finished", time_left_seconds=999)), 1.0) - - def test_a_pending_race_leaves_the_field_at_the_gate(self): - self.assertEqual(derby.elapsed_fraction(race("pending")), 0.0) - - def test_a_live_race_runs_on_the_clock(self): - # 12 hours long, 6 remaining. - self.assertAlmostEqual(derby.elapsed_fraction(race("live")), 0.5) - - def test_a_live_race_with_an_unusable_clock_stays_at_the_gate(self): - self.assertEqual(derby.elapsed_fraction(race("live", end_time=None)), 0.0) - self.assertEqual(derby.elapsed_fraction(race("live", time_left_seconds=None)), 0.0) - self.assertEqual(derby.elapsed_fraction(race("live", time_left_seconds=True)), 0.0) - - def test_the_clock_is_clamped_at_both_ends(self): - self.assertEqual(derby.elapsed_fraction(race("live", time_left_seconds=99_999)), 0.0) - self.assertEqual(derby.elapsed_fraction(race("live", time_left_seconds=-10)), 1.0) - - def test_position_scales_by_the_clock_and_not_just_by_the_leader(self): - # Leader-relative alone pins the front-runner to the finish line from - # the first minute, which makes a twelve-hour race look permanently - # over. The leader's position *is* the race's progress. - self.assertAlmostEqual(derby.position(100, 100, 0.5), 0.5) - self.assertAlmostEqual(derby.position(50, 100, 0.5), 0.25) - - def test_a_race_nobody_has_scored_in_does_not_divide_by_zero(self): - self.assertEqual(derby.position(0, 0, 0.5), 0.0) - - -class Scoring(unittest.TestCase): - - def test_the_bar_draws_what_the_race_is_ranked_on(self): - # Drawing current_tokens instead put a 4th-placed horse's bar ahead of - # 2nd's: the league discounts raw usage, so the two diverge. - self.assertEqual(derby.scored(horse(current_tokens=1000, scored_tokens=900)), 900) - - def test_a_race_that_is_not_scoring_falls_back_to_raw_usage(self): - entry = horse() - del entry["scored_tokens"] - self.assertEqual(derby.scored(entry), 1000) - - -class Document(unittest.TestCase): - - def build(self, **kwargs): - return derby.document(race(**kwargs)) - - def test_the_header_names_the_race_and_its_state(self): - doc = self.build(horses=[horse()]) - self.assertEqual(doc["schema"], 1) - self.assertEqual(doc["state"], "ok") - self.assertEqual(doc["header"]["title"], "StackOne Token League") - self.assertEqual(doc["header"]["badge"], {"text": "LIVE", "tone": "success"}) - self.assertEqual(doc["header"]["trailing"], "6h") - - def test_only_a_live_race_gets_a_countdown(self): - self.assertNotIn("trailing", self.build(status="finished", horses=[horse()])["header"]) - self.assertEqual(self.build(status="pending", horses=[horse()])["header"]["badge"]["tone"], - "warning") - - def test_a_row_carries_every_field_the_built_in_tab_drew(self): - row = self.build(horses=[horse()])["rows"][0] - self.assertEqual(row["id"], "h1") - self.assertEqual(row["lead"], "1") - self.assertEqual(row["title"], "black & white") - self.assertEqual(row["subtitle"], "Yashika") - self.assertEqual(row["value"], "900") - self.assertEqual(row["footnote"], "36K/15m · Premier Division") - self.assertEqual(row["track"]["tint"], "#FFFFFF") - - def test_an_unranked_horse_still_lines_up_with_the_ranked_ones(self): - self.assertEqual(self.build(horses=[horse(rank=None)])["rows"][0]["lead"], "–") - - def test_a_horse_with_no_colour_gets_the_default_coat(self): - row = self.build(horses=[horse(colors=None)])["rows"][0] - self.assertEqual(row["track"]["tint"], derby.DEFAULT_COAT) - self.assertEqual(runner_of(row)["palette"]["H"], derby.DEFAULT_COAT) - - # Every colour the document carries has to be one the host will read back. - def test_every_emitted_colour_is_in_the_form_the_host_accepts(self): - doc = self.build(horses=[horse(colors={"body": "ff0000"}), - horse("h2", colors={"body": "bogus"}), - horse("h3", colors=None)]) - emitted = [] - for row in doc["rows"]: - emitted.append(row["track"]["tint"]) - for ornament in row["ornaments"]: - emitted.extend(ornament["palette"].values()) - for colour in emitted: - self.assertIsNotNone(derby.parse_hex(colour), colour) - self.assertTrue(colour.startswith("#"), colour) - self.assertEqual(len(colour), 7, colour) - - def test_the_mane_differs_from_the_coat(self): - for body in ["#FFFFFF", "#000000", "#7FD1B9"]: - row = self.build(horses=[horse(colors={"body": body})])["rows"][0] - palette = runner_of(row)["palette"] - self.assertNotEqual(palette["H"], palette["M"], body) - - def test_only_a_live_runner_burning_tokens_animates(self): - # A finished race is a standings table, and a timeline that redraws a - # row to show the same thing is the cost the compact widget already - # learned to avoid. - live = runner_of(self.build(horses=[horse()])["rows"][0]) - self.assertEqual(live["fps"], 7) - self.assertEqual(len(live["frames"]), 2) - - for still in (self.build(status="finished", horses=[horse()]), - self.build(horses=[horse(pace_15m=0)])): - ornament = runner_of(still["rows"][0]) - self.assertEqual(ornament["fps"], 0) - self.assertEqual(len(ornament["frames"]), 1) - - def test_server_order_is_the_ranking(self): - doc = self.build(horses=[horse("c", rank=3), horse("a", rank=1), horse("b", rank=2)]) - self.assertEqual([r["id"] for r in doc["rows"]], ["c", "a", "b"]) - - def test_the_footnote_degrades_one_half_at_a_time(self): - self.assertEqual(self.build(horses=[horse(pace_15m=0)])["rows"][0]["footnote"], - "Premier Division") - self.assertEqual(self.build(horses=[horse(division=None)])["rows"][0]["footnote"], - "36K/15m") - self.assertEqual( - self.build(horses=[horse(pace_15m=0, division=99)])["rows"][0]["footnote"], "") - - def test_a_division_index_outside_the_names_is_dropped(self): - # It is 1-based into league_division_names, and 0 is the off-by-one - # this invites. - self.assertEqual(derby.division_of(horse(division=0), ["Premier"]), None) - self.assertEqual(derby.division_of(horse(division=1), ["Premier"]), "Premier") - self.assertEqual(derby.division_of(horse(division=True), ["Premier"]), None) - - # The host trims every text field and drops a row whose title comes out - # empty, so a horse named " " cost its whole row — rank, value and bar — - # not just its name. - def test_a_blank_name_costs_the_name_and_not_the_row(self): - doc = self.build(horses=[horse(name=" "), horse("h2", name="")]) - self.assertEqual([r["id"] for r in doc["rows"]], ["h1", "h2"]) - self.assertEqual([r["title"] for r in doc["rows"]], ["Unnamed", "Unnamed"]) - - def test_a_blank_user_name_is_absent_rather_than_blank(self): - # An empty optional field is an absent one to the host; a subtitle of - # spaces would reserve space for nothing. - self.assertEqual(self.build(horses=[horse(user_name=" ")])["rows"][0]["subtitle"], "") - - # The host drops the second of a duplicate pair without saying so, and the - # id is what an action names a row by — two rows answering to one id is a - # row that acts on the wrong horse. - def test_two_horses_sharing_an_id_keep_the_better_placed_one(self): - doc = self.build(horses=[horse("dup", rank=1, scored_tokens=900), - horse("dup", rank=5, scored_tokens=100), - horse("other", rank=2)]) - self.assertEqual([r["id"] for r in doc["rows"]], ["dup", "other"]) - # Document order is rank order, so the survivor is the one in front. - self.assertEqual(doc["rows"][0]["lead"], "1") - - def test_an_id_that_is_a_number_does_not_collide_with_its_string(self): - doc = self.build(horses=[horse(1), horse("1"), horse(2)]) - self.assertEqual([r["id"] for r in doc["rows"]], ["1", "2"]) - - # 0 and False are falsy and are still ids. Dropping one cost its whole row - # *and* promoted the next horse to the finish line, because the leader is a - # max over whatever survived — so the wrong horse appeared to be winning. - def test_a_falsy_id_is_still_an_id(self): - doc = self.build(horses=[horse(0, name="Zero", scored_tokens=100), - horse(1, name="One", scored_tokens=50)]) - self.assertEqual([r["id"] for r in doc["rows"]], ["0", "1"]) - self.assertGreater(doc["rows"][0]["track"]["fill"], - doc["rows"][1]["track"]["fill"]) - - def test_a_horse_with_no_id_at_all_is_dropped(self): - entry = horse() - del entry["horse_id"] - self.assertEqual(self.build(horses=[entry, horse("h2")])["rows"][0]["id"], "h2") - - # The dedupe key and the emitted id are derived once, so they cannot differ: - # trimming in one place and emitting untrimmed in the other had " 1 " - # dedupe as "1" and then render with its spaces. - def test_the_deduped_id_is_the_emitted_id(self): - doc = self.build(horses=[horse(" 1 "), horse("1"), horse("2")]) - self.assertEqual([r["id"] for r in doc["rows"]], ["1", "2"]) - - def test_an_entry_without_an_id_is_not_a_horse(self): - doc = self.build(horses=[horse(), {"name": "nameless"}, "nonsense", None]) - self.assertEqual([r["id"] for r in doc["rows"]], ["h1"]) - - def test_a_race_with_no_runners_says_so_rather_than_drawing_nothing(self): - doc = self.build(horses=[]) - self.assertEqual(doc["state"], "empty") - self.assertTrue(doc["message"]) - self.assertEqual(doc["rows"], []) - - # The post is anchored trailing, so it sits at the end of the track whatever - # the fill is doing — that is what makes it a line rather than something the - # horse drags along. Still, too: a chequer that animated would be a fault. - def test_every_row_gets_a_finish_post(self): - for status in ["live", "finished", "pending"]: - row = self.build(status=status, horses=[horse()])["rows"][0] - post = post_of(row) - self.assertEqual(post["fps"], 0, status) - self.assertEqual(len(post["frames"]), 1, status) - - # The horse draws over the post at the line rather than under it. - def test_the_horse_draws_on_top_of_the_post(self): - row = self.build(horses=[horse()])["rows"][0] - self.assertEqual([o["anchor"] for o in row["ornaments"]], - ["trailing", "fill-edge"]) - - # Its palette is fixed rather than taken from the coat, so a white horse - # doesn't get an invisible finish line. - def test_the_post_keeps_its_own_colours(self): - for body in ["#FFFFFF", "#000000"]: - post = post_of(self.build(horses=[horse(colors={"body": body})])["rows"][0]) - self.assertEqual(post["palette"], derby.FINISH_PALETTE) - self.assertNotEqual(post["palette"]["W"], post["palette"]["K"]) - - def test_the_post_alternates_every_row(self): - rows = derby.FINISH_POST - self.assertTrue(all(len(r) == 2 for r in rows)) - for above, below in zip(rows, rows[1:]): - self.assertNotEqual(above, below) - - def test_the_sync_action_is_bound_to_a_key_the_host_will_accept(self): - # An action whose key request is refused has no shortcut and no button, - # so it would be unreachable. - action = self.build(horses=[horse()])["actions"][0] - self.assertEqual(action["key"], "r") - - def test_a_race_carrying_a_non_finite_number_still_produces_a_document(self): - doc = self.build(horses=[horse(scored_tokens=float("inf"), - current_tokens=float("nan"), - pace_15m=float("inf"))]) - self.assertEqual(doc["rows"][0]["value"], "0") - # And it still round-trips: a bare NaN in the output is a blank pane. - self.assertEqual(json.loads(json.dumps(doc)), doc) - - def test_the_whole_document_survives_a_json_round_trip(self): - # The host reads one JSON object from stdout and nothing else. A value - # json.dump refuses is a blank pane, not a wrong number. - doc = self.build(horses=[horse(), horse("h2", rank=2, colors={"body": "#123"})]) - self.assertEqual(json.loads(json.dumps(doc)), doc) - - -class Sprite(unittest.TestCase): - - def test_both_frames_stay_inside_the_hosts_caps(self): - # 32 frames x 24 rows x 64 columns, per docs/extensions.md. - for frame in (derby.HORSE_STANDING, derby.HORSE_EXTENDED, derby.FINISH_POST): - self.assertLessEqual(len(frame), 24) - self.assertTrue(all(len(row) <= 64 for row in frame)) - - def test_the_two_frames_differ(self): - # An animation whose frames are identical costs a timeline and buys - # nothing. - self.assertNotEqual(derby.HORSE_STANDING, derby.HORSE_EXTENDED) - - def test_every_frame_is_rectangular(self): - # Ragged frames are legal — the host sizes from the largest — but a - # ragged horse is a typo, not a design. - for frame in (derby.HORSE_STANDING, derby.HORSE_EXTENDED): - self.assertEqual(len({len(row) for row in frame}), 1, frame) - - def test_the_sprite_uses_only_palette_keys_it_declares(self): - for ornament, frames in ((derby.ornament_for("#FFFFFF", True), - (derby.HORSE_STANDING, derby.HORSE_EXTENDED)), - (derby.finish_line(), (derby.FINISH_POST,))): - palette = set(ornament["palette"]) - for frame in frames: - used = {c for row in frame for c in row if c != "."} - self.assertTrue(used <= palette, used - palette) - - -class Base(unittest.TestCase): - """The value comes from the user's own config file, so this is not a trust - boundary — but a base silently downgraded to http would send a request the - user believes is encrypted.""" - - def test_an_unset_base_means_the_public_instance(self): - self.assertEqual(derby.valid_base(""), derby.DEFAULT_BASE) - self.assertEqual(derby.valid_base(None), derby.DEFAULT_BASE) - - def test_https_is_accepted_and_its_trailing_slash_dropped(self): - self.assertEqual(derby.valid_base("https://example.test/api/"), - "https://example.test/api") - - # valid_base only checks the URL we type. urllib follows redirects, and - # Python's stock handler will happily send you from https to http — so - # without this the "https only" the settings field promises described the - # first request and nothing after it. - def test_a_redirect_off_https_is_refused(self): - handler = derby.NoDowngrade() - for target in ["http://evil.test/api", "ftp://evil.test"]: - with self.assertRaises(derby.urllib.error.URLError, msg=target): - handler.redirect_request(None, None, 302, "Found", {}, target) - - def test_a_redirect_that_stays_on_https_is_allowed(self): - # Delegates to the stock handler, which needs a real request to build - # the next one — so assert it gets that far rather than raising. - request = derby.urllib.request.Request("https://example.test/a") - result = derby.NoDowngrade().redirect_request( - request, None, 302, "Found", {}, "https://example.test/b") - self.assertIsNotNone(result) - self.assertEqual(result.full_url, "https://example.test/b") - - def test_anything_but_https_is_refused(self): - for raw in ["http://example.test/api", "file:///etc/passwd", - "ftp://example.test", "https://", "example.test", - "https://user:pw@example.test/api", - # urlsplit gives username "" for a password-only userinfo, - # and "" is falsy — so checking username alone let it pass. - "https://:pw@example.test/api", - "https://user@example.test/api"]: - self.assertIsNone(derby.valid_base(raw), raw) - - -class FakeResponse: - """Just enough of http.client.HTTPResponse for get_json. - - read1 rather than read, because that is what the script calls: read(n) - blocks until it has n bytes or hits EOF, so a dribbling response never - returns control and the deadline is never checked. - """ - - def __init__(self, body, content_type): - self._body = body.encode("utf-8") - self.headers = {"Content-Type": content_type} - - def read1(self, size=-1): - chunk, self._body = self._body[:size], self._body[size:] - return chunk - - def read(self, size=-1): - return self.read1(size) - - def __enter__(self): - return self - - def __exit__(self, *_): - return False - - -class Fetching(unittest.TestCase): - """The two functions that touch the network, with the socket taken out. - - These exist because of what the derby actually does with a name it doesn't - recognise, which is not what anything about the response suggests: it - answers with the single-page app's own index.html and a 200, so a mistyped - organisation is indistinguishable from a corrupt response unless something - checks the content type. - """ - - def stub(self, *responses): - """A stand-in for the module's opener. - - Patching urllib.request.urlopen is not enough: get_json goes through a - built opener so a redirect off https can be refused, and a stub that - misses that seam lets the tests reach the real network — which is how - this harness silently started making live requests once the opener - landed. - """ - remaining = list(responses) - calls = [] - timeouts = self.timeouts - - class FakeOpener: - def open(self, request, timeout=None): - calls.append(request.full_url) - # Recorded so the seam between the budget and the socket is - # actually asserted. Ignoring it left `remaining()` tested as - # pure arithmetic and nothing checking it ever reached a socket. - timeouts.append(timeout) - return remaining.pop(0) - - self.calls = calls - return FakeOpener() - - def raising_stub(self, make_error): - raised = self.raised - - class FakeOpener: - def open(self, request, timeout=None): - error = make_error(request.full_url) - raised.append(error) - raise error - - return FakeOpener() - - def setUp(self): - self._real = derby._opener - # HTTPError wraps an open file object. Left unclosed it surfaces as - # "ResourceWarning: Implicitly cleaning up " in the CI - # log, which makes a green run look like it isn't one. - self.raised = [] - self.timeouts = [] - - def tearDown(self): - derby._opener = self._real - for error in self.raised: - # Only HTTPError wraps a file object; a bare TimeoutError has - # nothing to close. - close = getattr(error, "close", None) - if callable(close): - close() - - def test_a_json_response_is_parsed(self): - derby._opener = self.stub( - FakeResponse('{"races": []}', "application/json")) - self.assertEqual(derby.get_json("https://example.test/api", derby.time.monotonic() + 9), {"races": []}) - - # The guard the whole error message rests on. Without it, index.html - # reaches json.loads and the failure reads as "the response wasn't - # readable" — which sends somebody looking for a fault that isn't there. - # A timeout is not an unreadable response. Saying "wasn't readable" sent - # someone looking for a fault in the data when the service was just slow. - def test_a_timeout_and_a_bad_body_say_different_things(self): - os_environ = derby.os.environ - derby.os.environ = {derby.ORG_KEY: "StackOne"} - try: - derby._opener = self.raising_stub(lambda url: TimeoutError("timed out")) - self.assertIn("too long", derby.build()["message"]) - - derby._opener = self.stub(FakeResponse("not json", "application/json")) - self.assertIn("readable", derby.build()["message"]) - finally: - derby.os.environ = os_environ - - def test_a_web_page_is_refused_rather_than_parsed(self): - derby._opener = self.stub( - FakeResponse("", "text/html; charset=utf-8")) - with self.assertRaises(derby.NotJSON): - derby.get_json("https://example.test/api", derby.time.monotonic() + 9) - - # The literals are not valid JSON, and letting them in only moves the - # failure somewhere less legible. - def test_infinity_and_nan_literals_are_refused_at_the_parse(self): - for literal in ["Infinity", "-Infinity", "NaN"]: - derby._opener = self.stub( - FakeResponse('{"x": %s}' % literal, "application/json")) - with self.assertRaises(ValueError, msg=literal): - derby.get_json("https://example.test/api", derby.time.monotonic() + 9) - - def test_a_response_with_no_content_type_is_refused(self): - derby._opener = self.stub(FakeResponse('{"races": []}', "")) - with self.assertRaises(derby.NotJSON): - derby.get_json("https://example.test/api", derby.time.monotonic() + 9) - - # The field is the service's, and a non-string there put a JSON object - # where the host's decoder wants a string — which fails the *whole* - # document, so the pane would say "wrong type for message" instead of - # showing the API's error. - def test_a_non_string_error_message_does_not_reach_the_document(self): - import io - for body in ['{"code":"X","message":{"a":1}}', '{"code":"X","message":7}', - '{"code":"X"}', 'not json']: - derby._opener = self.raising_stub( - lambda url, _b=body: derby.urllib.error.HTTPError( - url, 500, "err", {}, io.BytesIO(_b.encode()))) - os_environ = derby.os.environ - derby.os.environ = {derby.ORG_KEY: "StackOne"} - try: - doc = derby.build() - finally: - derby.os.environ = os_environ - self.assertIsInstance(doc["message"], str, body) - self.assertEqual(json.loads(json.dumps(doc)), doc) - - def test_a_web_page_on_the_org_route_means_no_such_org(self): - derby._opener = self.stub( - FakeResponse("", "text/html")) - with self.assertRaises(derby.UnknownOrg): - derby.fetch("https://example.test/api", "stackone", derby.time.monotonic() + 9) - - # The budget has to reach the socket, not just be computed. Both hops get a - # timeout, neither exceeds the per-request cap, and the second gets less - # than the first because the first spent some of the budget. - def test_each_hop_is_given_what_is_left_of_the_budget(self): - derby._opener = self.stub( - FakeResponse('{"races": [{"join_code": "A", "status": "live"}]}', - "application/json"), - FakeResponse('{"join_code": "A", "horses": []}', "application/json")) - derby.fetch("https://example.test/api", "StackOne", - derby.time.monotonic() + derby.TOTAL_BUDGET) - self.assertEqual(len(self.timeouts), 2) - for t in self.timeouts: - self.assertIsNotNone(t, "a hop was given no timeout at all") - self.assertLessEqual(t, derby.MAX_PER_REQUEST) - self.assertGreater(t, 0) - - # A hop that would start past the deadline raises instead of being handed a - # consolation second — granting one is how two hops end up past the host's - # limit, which is the thing the budget exists to stop. - def test_a_hop_past_the_deadline_is_refused(self): - with self.assertRaises(TimeoutError): - derby.remaining(derby.time.monotonic() - 1) - - def test_the_org_name_reaches_the_url_percent_encoded(self): - derby._opener = self.stub( - FakeResponse('{"races": [{"join_code": "A B", "status": "live"}]}', - "application/json"), - FakeResponse('{"join_code": "A B", "horses": []}', "application/json")) - derby.fetch("https://example.test/api", "Stack One", derby.time.monotonic() + 9) - self.assertEqual(self.calls[0], "https://example.test/api/organisations/Stack%20One/races") - self.assertEqual(self.calls[1], "https://example.test/api/races/A%20B") - - def test_an_org_with_no_races_is_nothing_rather_than_an_error(self): - derby._opener = self.stub( - FakeResponse('{"races": []}', "application/json")) - self.assertIsNone(derby.fetch("https://example.test/api", "StackOne", derby.time.monotonic() + 9)) - - # An unknown org is empty, not an error: nothing is broken and nothing - # needs reporting — the name just isn't one. - # Building the document used to sit outside build()'s try, so anything it - # raised escaped as a traceback. The host reads that as a crashed - # extension rather than as the extension reporting something. - def test_a_race_that_cannot_be_rendered_is_reported_rather_than_raised(self): - derby._opener = self.stub( - FakeResponse('{"races": [{"join_code": "A", "status": "live"}]}', - "application/json"), - FakeResponse('{"join_code": "A", "horses": "not a list"}', "application/json")) - os_environ = derby.os.environ - derby.os.environ = {derby.ORG_KEY: "StackOne"} - try: - doc = derby.build() - finally: - derby.os.environ = os_environ - self.assertIn(doc["state"], ("ok", "empty", "error")) - self.assertEqual(json.loads(json.dumps(doc)), doc) - - # Only a 404 on the *org* hop is about the organisation. The race list is - # re-read every 30s, so a race deleted between the two hops 404s the second - # one — and blaming the org there sends someone to correct a setting that - # was right. - def test_a_404_on_the_race_hop_does_not_blame_the_organisation(self): - import io - calls = {"n": 0} - listing = FakeResponse('{"races": [{"join_code": "A", "status": "live"}]}', - "application/json") - - raised = self.raised - - class FakeOpener: - def open(self, request, timeout=None): - calls["n"] += 1 - if calls["n"] == 1: - return listing - error = derby.urllib.error.HTTPError( - request.full_url, 404, "gone", {}, io.BytesIO(b"{}")) - raised.append(error) - raise error - - derby._opener = FakeOpener() - os_environ = derby.os.environ - derby.os.environ = {derby.ORG_KEY: "StackOne"} - try: - doc = derby.build() - finally: - derby.os.environ = os_environ - self.assertNotIn("organisation", doc["message"].lower()) - self.assertIn("race", doc["message"].lower()) - - def test_a_404_on_the_org_hop_still_blames_the_organisation(self): - import io - derby._opener = self.raising_stub( - lambda url: derby.urllib.error.HTTPError(url, 404, "no", {}, io.BytesIO(b"{}"))) - os_environ = derby.os.environ - derby.os.environ = {derby.ORG_KEY: "Nope"} - try: - doc = derby.build() - finally: - derby.os.environ = os_environ - self.assertIn("organisation", doc["message"].lower()) - - def test_build_reports_an_unknown_org_as_empty_and_says_why(self): - derby._opener = self.stub( - FakeResponse("", "text/html")) - os_environ = derby.os.environ - derby.os.environ = {derby.ORG_KEY: "stackone"} - try: - doc = derby.build() - finally: - derby.os.environ = os_environ - self.assertEqual(doc["state"], "empty") - self.assertIn("case-sensitive", doc["message"]) - - -if __name__ == "__main__": - unittest.main() diff --git a/extensions/pylon/manifest.json b/extensions/pylon/manifest.json deleted file mode 100644 index 6850bfa..0000000 --- a/extensions/pylon/manifest.json +++ /dev/null @@ -1,45 +0,0 @@ -{ - "id": "pylon", - "name": "Pylon", - "description": "Customer issues waiting on a response or with engineering, colour-coded, and a nudge before the first-response SLA runs out.", - "version": "1.2.0", - "schema": 1, - "tab": { - "label": "Pylon" - }, - "run": "./run", - "requires": [ - "python3" - ], - "config": [ - { - "key": "STACKNUDGE_EXT_PYLON_TOKEN", - "label": "API token", - "help": "Pylon \u2192 Settings \u2192 API Tokens. Under Act as user or bot, pick yourself, so the token has your access and no more, and the tab knows which issues are yours. It only reads, except x twice on a row, which tags that issue Spam and closes it." - }, - { - "key": "STACKNUDGE_EXT_PYLON_EMAIL", - "label": "Your Pylon email", - "help": "Only needed if the token doesn't act as you. Whose issues count as yours.", - "placeholder": "you@company.com" - }, - { - "key": "STACKNUDGE_EXT_PYLON_SYNC_MINUTES", - "label": "Sync every (minutes)", - "help": "How often to ask Pylon for changes, 1 to 60. A new ticket appears at the next sync. Countdowns update every minute, and Pylon is checked again before any reminder, so answered tickets don't ping. Press r in the tab to sync now.", - "placeholder": "3" - }, - { - "key": "STACKNUDGE_EXT_PYLON_NOTIFY", - "label": "Notifications", - "help": "on or off. Banners come from macOS (listed as Script Editor in System Settings \u2192 Notifications) and don't follow StackNudge's mute. Off keeps the tab and stops them.", - "placeholder": "on" - } - ], - "refresh": { - "onOpen": true, - "intervalSeconds": 60, - "whileFocusedOnly": false - }, - "glance": true -} diff --git a/extensions/pylon/run b/extensions/pylon/run deleted file mode 100755 index c5504f4..0000000 --- a/extensions/pylon/run +++ /dev/null @@ -1,1311 +0,0 @@ -#!/usr/bin/env python3 -"""Pylon: customer issues waiting on a response from us. - -Three kinds of row, told apart by the colour of their bar, the one thing on -a row an extension can colour. - -- **First response** (green, then amber, then red): an issue Pylon is running a - first-response SLA on that nobody has answered yet. Its bar fills as the SLA - runs down. -- **Reply owed** (blue): an issue we have answered before where Pylon's - next-reply SLA is running, because the customer has written since. -- **With engineering** (solid purple): an issue in an engineering state. It's - shown whether or not an SLA is running, and never reminded about, because - the next move is engineering's. - -A reply owed or an engineering ticket whose last word is the customer signing -off ("thanks", "sounds good") turns grey and reads "close?": still listed, but -below the real work and left out of the badge's count. - -Each row's footnote is the latest message on the issue — who, how long ago, -and its first line — so the list says what's going on without opening -anything. - -Both clocks are Pylon's own (`first_response_breach_time`, `next_reply`) -rather than ones worked out here. They are what the team is measured on, they -already know about business hours, and they are absent on the proactive -outreach issues we open ourselves — which otherwise look exactly like an -unanswered customer. - -Email issues with no account aren't asked for: that is how the spam that gets -past Pylon's own filter arrives. A no-account issue from anywhere else (the -chat widget, a Slack channel) is still listed, because real customers arrive -that way too. - -The host runs this every minute, tab hidden or not (`whileFocusedOnly` is -false), but Pylon is only asked every few minutes — the Sync setting, 3 by -default. The runs between redraw from the last sync: deadlines don't move -between syncs, so countdowns and reminders stay on the minute, and only a -brand-new issue waits for the next sync to appear. Before sending a reminder -it asks Pylon again, so an issue answered since the last sync doesn't ping. -`r` syncs now. - -The reminders are the point of running while the tab is hidden — the banner -that fires while you are looking at something else: - - when it opens the issue's owner: its assignee, or until somebody - is assigned, the account's owner - 2/3 of SLA left the owner again - 1/3 of SLA left the owner again - 1/6 of SLA left everyone - breached everyone - -The SLA is each issue's own window as Pylon sets it, from opening to its -first-response deadline. On a 30-minute SLA that is "instantly, then 10, 20 -and 25 minutes in", the escalation this was built for. An issue with no owner -is "ours": it goes to everyone at every stage, because its owner is then the -whole team. So does one whose owner's Pylon status is out of office. Out of hours, Pylon pushes the deadline to the next business -morning, so the window is long and its reminders are spread across it; a -laptop that slept through some gets one banner for the latest, not one each. - -Spam is marked from the tab: x on a row, then x again on it within -SPAM_CONFIRM_SECONDS, tags the issue Spam and closes it. That is the only -thing ever written to Pylon; everything else only reads. See -docs/extensions.md for the schema this prints. -""" - -import hashlib -import json -import os -import subprocess -import sys -import time -import urllib.error -import urllib.parse -import urllib.request -from datetime import datetime, timedelta, timezone -from html.parser import HTMLParser - -TOKEN_KEY = "STACKNUDGE_EXT_PYLON_TOKEN" -EMAIL_KEY = "STACKNUDGE_EXT_PYLON_EMAIL" -NOTIFY_KEY = "STACKNUDGE_EXT_PYLON_NOTIFY" -SYNC_KEY = "STACKNUDGE_EXT_PYLON_SYNC_MINUTES" -DEFAULT_SYNC_MINUTES = 3 - -# What a sync keeps of each issue: enough to draw its row, time its reminders -# and open it. Never the body, which is the customer's whole first message. -SNAPSHOT_FIELDS = ("id", "number", "title", "link", "state", "source", "account", "created_at", - "assignee", "first_response_time", "first_response_breach_time", - "next_reply", "latest_message_time", "snoozed_until_time") - -# US first. A token minted in the EU region is refused there with -# `wrong_region_token`; the region that answers is remembered in the state file. -BASES = ("https://api.usepylon.com", "https://api.eu.usepylon.com") - -# One budget across every hop, enforced here rather than by the socket — see -# the derby extension for why urlopen's timeout is not a total one. The -# deadline is checked before each blocking read, and each read can block for up -# to MAX_PER_REQUEST, so the worst case is the sum of the two. That sum is kept -# under the host's 12-second kill, which would otherwise end a slow run before -# it saved its state. -TOTAL_BUDGET = 8 -MAX_PER_REQUEST = 3 -HOST_TIMEOUT = 12 -READ_CHUNK = 65536 -# Every issue carries its full body, so a page of them is not small. -MAX_BODY_BYTES = 6 * 1024 * 1024 -# An error's body is read only for its code, so it is read only this far. -ERROR_BODY_BYTES = 64 * 1024 - -# Issues with no message in this long aren't fetched. Measured from the latest -# message, not from when the issue was opened: a customer writing today on a -# thread from August is owed a reply today, and windowing on creation hid five -# of those on the day this was measured. A month of silence is a backlog for -# Pylon's own views, not a nudge. -LOOKBACK_DAYS = 30 -# Small pages, followed while the time budget allows. A scan that can't finish -# is kept as partial rather than passed off as the whole queue. -SEARCH_LIMIT = 250 -MAX_PAGES = 20 -PAGE_RESERVE = 2.0 -MAX_ROWS = 200 - -# A reminder is only sent from a snapshot this fresh. Anything older is synced -# first: the issue may have been answered since, and a reminder about an -# answered issue is how a reminder stops being believed. -FRESH_FOR_BANNER = 60 - -# The latest message on each row. A thread is fetched only on a sync and only -# when its latest_message_time has moved, at most this many a sync, and only -# while this much of the time budget is left — so a cold cache fills in over a -# couple of syncs instead of blowing the host's deadline on the first. -PREVIEWS_PER_POLL = 8 -PREVIEW_RESERVE = 2.5 -MESSAGE_PAGES = 3 -PREVIEW_CHARS = 200 -# Bumped when a preview gains a field or one changes meaning, so cached ones are -# fetched again rather than read wrongly: a preview's cache otherwise lives until -# its thread moves. -PREVIEW_VERSION = 3 - -# A customer's last word that reads like signing off, on a ticket we'd -# otherwise owe a reply on, makes the row a "close?" rather than work. Short -# and without a question, because a long message that happens to say thanks -# usually says something else too. -SIGN_OFFS = ("thank", "thx", "cheers", "sounds good", "all good", "no further action", - "perfect", "great", "nice", "awesome", "brilliant", "lovely", - "appreciate", "got it", "that works", "will do") -SIGN_OFF_CHARS = 160 - -# A Pylon user status meaning "don't count on me". Their tickets are the team's -# while it lasts. -AWAY_STATUSES = ("out_of_office",) - -# States in which nothing is owed by us: the customer has the ball, somebody -# parked it on purpose, or it is done. -NOT_ON_US = ["closed", "waiting_on_customer", "on_hold"] - -# States meaning the ticket is with engineering. Pylon lets a workspace add its -# own states, and this is the one in use where this was built. Such a ticket is -# shown whether or not an SLA is running, so it doesn't vanish while it waits. -# It isn't reminded about, because the next move is engineering's. -ENGINEERING_STATES = ("waiting_on_engineering",) - -# Tagged and closed rather than Pylon's own mark-spam, which deletes the issue -# and blocks its sender with no undo. The tag is what reports leave spam out by. -SPAM_TAG = "Spam" -# The second x has to land this soon after the first, on the same row, so one -# stray key can't close a customer's issue. -SPAM_CONFIRM_SECONDS = 10 - -ME_TTL = 24 * 3600 -# Hourly rather than daily: the list carries each person's status, and an -# out-of-office owner should hand their tickets to the team the same day. -USERS_TTL = 3600 -ACCOUNTS_TTL = 6 * 3600 - -# (share of the SLA window still left, who hears about it), first to last. -# The window is each issue's own, as Pylon sets it: from when the issue was -# opened to its first-response deadline. Pylon's API exposes the deadline but -# not the SLA's length, so this is the only length there is to go on — and -# nothing here assumes one. On a 30-minute SLA these land at 30, 20, 10 and 5 -# minutes left and at breach; on a 4-hour one, at 4h, 2h40, 1h20 and 40m. -STAGES = [ - (1.0, "owner"), - (2 / 3, "owner"), - (1 / 3, "owner"), - (1 / 6, "team"), - (0.0, "team"), -] -# Only for an issue with no usable opening time to measure a window from, -# which Pylon's schema says can't happen: `created_at` is required. -FALLBACK_WINDOW = 30 * 60 -SOUNDS = {1: "Glass", 2: "Ping", 3: "Ping", 4: "Sosumi", 5: "Basso"} -# An issue first seen already this far past its SLA is shown but never -# bannered. Without it the first run after install pings every stale issue in -# the workspace at once. -SILENT_AFTER_BREACH = 60 * 60 -# More banners than this in one run collapse into a single summary. -MAX_BANNERS = 3 - -# The bar is the one thing on a row an extension can colour, so it carries the -# category: green to amber to red for a first response as its deadline nears, -# blue for a reply owed, purple for a ticket with engineering. -GREEN, AMBER, RED = "#7FD1B9", "#E8A87C", "#E5534B" -BLUE, PURPLE = "#6FA8DC", "#A78BDB" -# A "close?": still listed, but the customer has said they're done. -GREY = "#9AA0A6" - -_state_path = "state.json" - - -# --- Time and text ---------------------------------------------------------- - -def parse_time(value): - """RFC 3339 from Pylon, or None. Python 3.9's fromisoformat has no "Z".""" - if not isinstance(value, str) or not value: - return None - try: - parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) - except ValueError: - return None - return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc) - - -def short_duration(seconds): - seconds = max(0, int(seconds)) - if seconds < 60: - return "<1m" - if seconds < 3600: - return "%dm" % (seconds // 60) - hours, minutes = seconds // 3600, (seconds % 3600) // 60 - if hours < 24: - return "%dh %02dm" % (hours, minutes) if minutes else "%dh" % hours - days, hours = hours // 24, hours % 24 - return "%dd %dh" % (days, hours) if hours else "%dd" % days - - -def clock(moment, now): - """A due time as the reader's wall clock: "14:30", or "Mon 09:30" when it - isn't today.""" - local, today = moment.astimezone(), now.astimezone() - if local.date() == today.date(): - return local.strftime("%H:%M") - return local.strftime("%a %H:%M") - - -def text(value): - """One line of display text. Issue titles are the customer's own, and a - newline in one would otherwise be a row the host can only half draw.""" - return " ".join(value.split()) if isinstance(value, str) else "" - - -class _VisibleText(HTMLParser): - """The text a reader would see. Block boundaries become spaces, so - "

Hi

there

" reads "Hi there" rather than "Hithere", and an - email's ' - '

Hi @Sam Taylor,

' - '
  • Q&A done
  • next

Thanks') - self.assertEqual(pylon.plain(html), "Hi @Sam Taylor, Q&A done next Thanks") - self.assertEqual(pylon.plain(None), "") - - def test_the_latest_message_wins_whatever_order_it_arrives_in(self): - users = {ALEX: {"name": "Alex Rivera", "email": "alex@example.com"}} - preview = pylon.preview_of([message(ALEX, "

newer

", 5), - message("Dana", "

older

", 50)], users) - self.assertEqual((preview["who"], preview["text"], preview["note"]), - ("Alex", "newer", False)) - self.assertIsNone(pylon.preview_of([], users)) - - def test_footnote_puts_the_message_last_so_truncation_eats_it_first(self): - row = pylon.row_for(dict(item(), preview={ - "who": "Dana", "at": stamp(NOW - timedelta(hours=3)), "text": "It broke", "note": False}), NOW) - self.assertEqual(row["footnote"], "yours · Dana, 3h ago: It broke") - - def test_durations(self): - self.assertEqual(pylon.short_duration(30), "<1m") - self.assertEqual(pylon.short_duration(25 * 60), "25m") - self.assertEqual(pylon.short_duration(2 * 3600), "2h") - self.assertEqual(pylon.short_duration(26 * 3600), "1d 2h") - - -# --- End to end against a fake Pylon ---------------------------------------- - -class _Response: - def __init__(self, payload): - self._body = io.BytesIO(json.dumps(payload).encode("utf-8")) - self.headers = {"Content-Type": "application/json"} - - def read1(self, size): - return self._body.read1(size) - - def __enter__(self): - return self - - def __exit__(self, *exc): - return False - - -def http_error(status, code=None): - body = json.dumps({"code": code, "request_id": "r"} if code else {"request_id": "r"}) - return urllib.error.HTTPError("https://api.usepylon.com", status, "error", {}, - io.BytesIO(body.encode("utf-8"))) - - -class _FakePylon: - def __init__(self, routes): - self.routes = routes - self.requests = [] - - def open(self, request, timeout=None): - url = urllib.parse.urlsplit(request.full_url) - body = json.loads(request.data) if request.data else None - self.requests.append((url.netloc, request.get_method(), url.path, body, request)) - handler = self.routes.get((request.get_method(), url.path)) - if handler is None and url.path.startswith("/issues/") and url.path.endswith("/messages"): - handler = self.routes.get((request.get_method(), "/issues/*/messages")) - if handler is None: - raise AssertionError("unexpected %s %s" % (request.get_method(), url.path)) - result = handler(url.netloc, body, url.path) if callable(handler) else handler - if isinstance(result, Exception): - raise result - return _Response(result) - - -def message(author, html, minutes_ago, private=False): - who = ({"user": {"id": author}, "name": "ignored"} if author.startswith("user-") - else {"contact": {"id": "c-" + author}, "name": author}) - return {"id": "m-%s-%d" % (author, minutes_ago), "author": who, "message_html": html, - "is_private": private, "timestamp": stamp(NOW - timedelta(minutes=minutes_ago))} - - -THREADS = { - "issue-1": [message("Robin Vale", "

Hi team,

Any update on the & export fix?

", 125)], - "issue-2": [message("Dana", "

It broke again

", 300), - message(ALEX, "

Looking into it with engineering

", 40, private=True)], - "issue-3": [], -} - - -def messages_route(host, body, path): - return {"data": THREADS.get(path.split("/")[2], []), "request_id": "r"} - - -def message_calls(fake): - return [r[2].split("/")[2] for r in fake.requests if r[2].endswith("/messages")] - - -def workspace(): - return { - ("GET", "/issues/*/messages"): messages_route, - ("GET", "/me"): {"data": {"id": "org", "name": "StackOne", - "user": {"id": ME, "email": "me@example.com"}}}, - ("GET", "/users"): {"data": [ - {"id": ME, "name": "Sam Taylor", "email": "me@example.com"}, - {"id": ALEX, "name": "Alex Rivera", "email": "alex@example.com"}, - ]}, - ("POST", "/issues/search"): {"data": [ - issue(1, account={"id": "acct-mine"}), - issue(2, account={"id": "acct-alex"}, created_at=stamp(NOW - timedelta(minutes=26)), - first_response_breach_time=stamp(NOW + timedelta(minutes=4))), - issue(3, account=None, created_at=stamp(NOW - timedelta(days=3, minutes=30)), - first_response_breach_time=stamp(NOW - timedelta(days=3))), - issue(4, first_response_breach_time=None, tags=["proactive-nudge"]), - issue(7, account={"id": "acct-feedback"}), - ], "pagination": {"has_next_page": False}}, - # Owners come back as a bare id: the live API omits the email the docs - # promise, so "yours" has to go through /users. - ("POST", "/accounts/search"): {"data": [ - {"id": "acct-mine", "name": "Acme", "type": "customer", "owner": {"id": ME}}, - {"id": "acct-alex", "name": "Globex", "type": "customer", "owner": {"id": ALEX}}, - {"id": "acct-feedback", "name": "Product Feedback", "type": "internal", "owner": None}, - ]}, - } - - -class EndToEnd(unittest.TestCase): - - def setUp(self): - self.dir = tempfile.TemporaryDirectory() - self.addCleanup(self.dir.cleanup) - patcher = mock.patch.object(pylon, "_state_path", os.path.join(self.dir.name, "state.json")) - patcher.start() - self.addCleanup(patcher.stop) - self.env = {pylon.TOKEN_KEY: "secret-token"} - self.banners, self.opened = [], [] - - def run_once(self, fake, argv=(), env=None, now=NOW): - out = io.StringIO() - with mock.patch.object(pylon, "_opener", fake), \ - mock.patch.object(pylon, "_notifier", lambda *a: self.banners.append(a)), \ - mock.patch.object(pylon, "_launcher", self.opened.append), \ - mock.patch.dict(os.environ, self.env if env is None else env, clear=True), \ - contextlib.redirect_stdout(out), \ - contextlib.redirect_stderr(io.StringIO()): - status = pylon.main(list(argv), now=now) - return status, (json.loads(out.getvalue()) if out.getvalue() else None) - - def test_without_a_token_it_asks_for_one(self): - status, doc = self.run_once(_Forbidden(), env={}) - self.assertEqual((status, doc["state"]), (0, "empty")) - self.assertIn("API token", doc["message"]) - - def test_a_poll_lists_what_is_waiting_and_pings_the_owner(self): - fake = _FakePylon(workspace()) - status, doc = self.run_once(fake) - self.assertEqual(status, 0) - self.assertEqual([r["id"] for r in doc["rows"]], ["issue-2", "issue-1", "issue-3"]) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertIn("yours", footnotes["issue-1"]) - self.assertIn("Alex", footnotes["issue-2"]) - self.assertIn("ours", footnotes["issue-3"]) - # Mine at 30 left, Alex's at 4 left (a team stage). The three-day-old - # breach is on screen and silent. - self.assertEqual(sorted(b[0] for b in self.banners), - ["Pylon #1 · 30m left", "Pylon #2 · 4m left"]) - - # The token rides only as an unredirected header, so it can't follow a - # redirect anywhere. - request = fake.requests[0][4] - self.assertIn("Authorization", request.unredirected_hdrs) - self.assertNotIn("Authorization", request.headers) - - # The next run, inside the sync interval, asks Pylon nothing and pings - # nobody again. - fake.requests.clear() - self.banners.clear() - self.run_once(fake) - self.assertEqual(fake.requests, []) - self.assertEqual(self.banners, []) - - # A sync reuses who-is-who: one search, and no thread fetched again. - self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual([r[2] for r in fake.requests], ["/issues/search"]) - - def test_internal_channels_routed_into_pylon_are_not_customers(self): - status, doc = self.run_once(_FakePylon(workspace())) - self.assertEqual(status, 0) - self.assertNotIn("issue-7", [r["id"] for r in doc["rows"]]) - self.assertNotIn("Pylon #7", " ".join(b[0] for b in self.banners)) - - def press_x(self, fake, row="issue-1", now=NOW, env=None): - return self.run_once(fake, argv=["--action", "spam", "--row", row], now=now, env=env) - - @staticmethod - def patches(fake): - return [(r[2], r[3]) for r in fake.requests if r[1] == "PATCH"] - - def test_x_twice_on_a_row_tags_it_spam_and_closes_it(self): - routes = workspace() - routes[("PATCH", "/issues/issue-1")] = {"data": {"id": "issue-1"}, "request_id": "r"} - fake = _FakePylon(routes) - self.run_once(fake) - - # The first x only arms the row: nothing is written. - _, doc = self.press_x(fake) - self.assertEqual(self.patches(fake), []) - self.assertEqual({r["id"]: r for r in doc["rows"]}["issue-1"]["value"], "x again: spam") - - _, doc = self.press_x(fake, now=NOW + timedelta(seconds=3)) - self.assertEqual(self.patches(fake), [("/issues/issue-1", { - "tags": ["Spam"], "tags_apply_mode": "append_only", "state": "closed"})]) - # Gone at once, not at the next sync. - self.assertNotIn("issue-1", [r["id"] for r in doc["rows"]]) - self.assertIn("#1 marked as spam", doc["header"]["title"]) - - def test_a_second_x_too_late_only_arms_the_row_again(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - self.press_x(fake) - _, doc = self.press_x(fake, now=NOW + timedelta(seconds=pylon.SPAM_CONFIRM_SECONDS)) - self.assertEqual(self.patches(fake), []) - self.assertEqual({r["id"]: r for r in doc["rows"]}["issue-1"]["value"], "x again: spam") - - def test_x_on_another_row_or_another_key_in_between_starts_over(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - self.press_x(fake, row="issue-1") - _, doc = self.press_x(fake, row="issue-2") - rows = {r["id"]: r for r in doc["rows"]} - self.assertEqual(rows["issue-2"]["value"], "x again: spam") - self.assertNotEqual(rows["issue-1"]["value"], "x again: spam") - self.run_once(fake, argv=["--action", "mine"]) - self.press_x(fake, row="issue-2") - self.assertEqual(self.patches(fake), []) - - def test_x_writes_only_to_an_issue_the_tab_is_showing(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - fake.requests.clear() - # issue-7 is on an internal account, so it was never in the list. - for row in ("issue-7", "issue-99", "../users"): - self.press_x(fake, row=row) - self.press_x(fake, row=row) - self.assertEqual(fake.requests, []) - - def test_x_never_writes_with_a_token_the_list_did_not_come_from(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - self.press_x(fake) - self.press_x(fake, env={pylon.TOKEN_KEY: "another-token"}) - self.assertEqual(self.patches(fake), []) - - def test_a_failed_spam_keeps_the_row_and_says_why(self): - self.run_once(_FakePylon(workspace())) - for failure, said in ((http_error(403, "forbidden"), "#1 not marked as spam: Pylon refused"), - (http_error(404, "not_found"), "#1 not marked as spam (Pylon 404)"), - (http_error(503), "#1 not marked as spam, try again")): - with self.subTest(said=said): - routes = workspace() - routes[("PATCH", "/issues/issue-1")] = failure - fake = _FakePylon(routes) - self.press_x(fake) - status, doc = self.press_x(fake) - self.assertEqual(len(self.patches(fake)), 1) - self.assertEqual(status, 0) - self.assertIn("issue-1", [r["id"] for r in doc["rows"]]) - self.assertIn(said, doc["header"]["title"]) - - def test_the_search_asks_only_for_issues_that_could_be_on_us(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - search = next(r[3] for r in fake.requests if r[2] == "/issues/search") - state_filter, not_spam, either = search["filter"]["subfilters"] - self.assertEqual(state_filter, {"field": "state", "operator": "not_in", - "values": ["closed", "waiting_on_customer", "on_hold"]}) - # Spam that gets past Pylon's own filter is email with no account: - # never fetched. No-account issues from anywhere else still are. - self.assertEqual(not_spam, {"operator": "or", "subfilters": [ - {"field": "account_id", "operator": "is_set"}, - {"field": "source", "operator": "not_in", "values": ["email"]}, - ]}) - window, engineering = either["subfilters"] - self.assertEqual(either["operator"], "or") - # Windowed on the latest message, not on creation: a customer writing - # today on an old thread is owed a reply today. - self.assertEqual(window["field"], "latest_message_activity_at") - self.assertEqual(window["value"], stamp(NOW - timedelta(days=pylon.LOOKBACK_DAYS))) - # ...or with engineering, however long it has been quiet. - self.assertEqual(engineering, {"field": "state", "operator": "in", - "values": ["waiting_on_engineering"]}) - - def test_notifications_off_keeps_the_tab_and_drops_the_banners(self): - env = dict(self.env, **{pylon.NOTIFY_KEY: "off"}) - status, doc = self.run_once(_FakePylon(workspace()), env=env) - self.assertEqual((status, len(doc["rows"]), self.banners), (0, 3, [])) - - def test_the_email_setting_decides_whose_issues_are_yours(self): - env = dict(self.env, **{pylon.EMAIL_KEY: "alex@example.com"}) - routes = workspace() - del routes[("GET", "/me")] # the setting means /me isn't asked - _, doc = self.run_once(_FakePylon(routes), env=env) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertIn("yours", footnotes["issue-2"]) - self.assertIn("Sam", footnotes["issue-1"]) - - def test_a_refused_token_says_so(self): - routes = workspace() - routes[("GET", "/me")] = http_error(401, "invalid_api_token") - status, doc = self.run_once(_FakePylon(routes)) - self.assertEqual((status, doc["state"]), (0, "error")) - self.assertIn("refused the API token", doc["message"]) - - def test_an_eu_token_falls_back_and_the_region_is_remembered(self): - routes = workspace() - for key, payload in list(routes.items()): - routes[key] = (lambda payload: lambda host, body, path: ( - (payload(host, body, path) if callable(payload) else payload) - if host == "api.eu.usepylon.com" - else http_error(401, "wrong_region_token")))(payload) - fake = _FakePylon(routes) - status, doc = self.run_once(fake) - self.assertEqual((status, len(doc["rows"])), (0, 3)) - fake.requests.clear() - self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual({r[0] for r in fake.requests}, {"api.eu.usepylon.com"}) - - def test_rate_limiting_is_transient_and_keeps_the_last_document(self): - routes = workspace() - routes[("POST", "/issues/search")] = http_error(429, "rate_limited") - status, doc = self.run_once(_FakePylon(routes)) - self.assertEqual((status, doc), (1, None)) - - def test_return_opens_the_selected_issue_in_pylon(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - self.run_once(fake, argv=["--action", "open", "--row", "issue-1"]) - self.assertEqual(self.opened, ["https://app.usepylon.com/issues?issueNumber=1"]) - - def test_m_toggles_mine_only(self): - routes = workspace() - routes[("POST", "/issues/search")]["data"].append(issue( - 8, account={"id": "acct-alex"}, state="waiting_on_you", - first_response_time=stamp(NOW), first_response_breach_time=None, - next_reply={"time": None, "breach_time": stamp(NOW + timedelta(hours=2))})) - fake = _FakePylon(routes) - _, doc = self.run_once(fake, argv=["--action", "mine"]) - # Alex's reply owed goes; every first response, Alex's included, stays. - self.assertEqual([r["id"] for r in doc["rows"]], ["issue-2", "issue-1", "issue-3"]) - _, doc = self.run_once(fake, argv=["--action", "mine"]) - self.assertEqual(len(doc["rows"]), 4) - - def test_rows_say_who_spoke_last_how_long_ago_and_what_they_said(self): - _, doc = self.run_once(_FakePylon(workspace())) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertEqual(footnotes["issue-1"], - "yours · Robin Vale, 2h 05m ago: Hi team, Any update on the & export fix?") - # A teammate by first name, and an internal note says so. - self.assertEqual(footnotes["issue-2"], - "Alex · Alex (note), 40m ago: Looking into it with engineering") - # No messages: the ordinary footnote stays. - self.assertIn("first response missed", footnotes["issue-3"]) - - def test_a_thread_is_fetched_again_only_when_it_moves(self): - routes = workspace() - fake = _FakePylon(routes) - sync = ["--action", "refresh"] - self.run_once(fake) - self.assertEqual(sorted(message_calls(fake)), ["issue-1", "issue-2", "issue-3"]) - fake.requests.clear() - self.run_once(fake, argv=sync) - self.assertEqual(message_calls(fake), []) - search = routes[("POST", "/issues/search")]["data"] - search[0]["latest_message_time"] = stamp(NOW + timedelta(minutes=1)) - fake.requests.clear() - self.run_once(fake, argv=sync) - self.assertEqual(message_calls(fake), ["issue-1"]) - - def test_previews_fill_in_over_polls_most_urgent_first(self): - fake = _FakePylon(workspace()) - with mock.patch.object(pylon, "PREVIEWS_PER_POLL", 1): - _, doc = self.run_once(fake) - self.assertEqual(message_calls(fake), ["issue-2"]) # 4 minutes left: first - self.assertIn("Alex (note)", doc["rows"][0]["footnote"]) - fake.requests.clear() - self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual(message_calls(fake), ["issue-1"]) - - def test_a_failed_preview_costs_the_footnote_not_the_poll(self): - routes = workspace() - routes[("GET", "/issues/*/messages")] = http_error(404, "not_found") - status, doc = self.run_once(_FakePylon(routes)) - self.assertEqual((status, len(doc["rows"])), (0, 3)) - self.assertIn("first response due", doc["rows"][1]["footnote"]) - - def test_rate_limited_previews_stop_for_this_poll(self): - routes = workspace() - routes[("GET", "/issues/*/messages")] = http_error(429, "rate_limited") - fake = _FakePylon(routes) - status, doc = self.run_once(fake) - self.assertEqual((status, len(doc["rows"])), (0, 3)) - self.assertEqual(len(message_calls(fake)), 1) - - def test_a_preview_of_a_thread_that_moved_on_is_dropped_not_shown(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - routes[("POST", "/issues/search")]["data"][0]["latest_message_time"] = stamp( - NOW + timedelta(minutes=1)) - with mock.patch.object(pylon, "PREVIEWS_PER_POLL", 0): - _, doc = self.run_once(fake, argv=["--action", "refresh"]) - footnote = next(r["footnote"] for r in doc["rows"] if r["id"] == "issue-1") - self.assertNotIn("Robin", footnote) - - # --- Sync interval --------------------------------------------------- - - def test_between_syncs_pylon_is_not_asked_and_the_clock_still_runs(self): - self.run_once(_FakePylon(workspace())) - status, doc = self.run_once(_Forbidden(), now=NOW + timedelta(minutes=2)) - self.assertEqual(status, 0) - rows = {r["id"]: r for r in doc["rows"]} - self.assertEqual(rows["issue-1"]["value"], "28m left") - self.assertIn("Robin Vale", rows["issue-1"]["footnote"]) # previews survive - self.assertEqual(doc["header"]["title"], "Waiting on us · synced 2m ago") - - def test_the_sync_setting_decides_how_often_pylon_is_asked(self): - env = dict(self.env, **{pylon.SYNC_KEY: "5"}) - routes = workspace() - # Nothing comes due in these five minutes, so only the setting decides. - routes[("POST", "/issues/search")]["data"][1]["first_response_breach_time"] = stamp( - NOW + timedelta(minutes=40)) - fake = _FakePylon(routes) - self.run_once(fake, env=env) - fake.requests.clear() - self.run_once(fake, env=env, now=NOW + timedelta(minutes=4, seconds=59)) - self.assertEqual(fake.requests, []) - self.run_once(fake, env=env, now=NOW + timedelta(minutes=5)) - self.assertEqual([r[2] for r in fake.requests], ["/issues/search"]) - - def test_the_default_is_every_three_minutes(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - fake.requests.clear() - self.run_once(fake, now=NOW + timedelta(minutes=2, seconds=59)) - self.assertEqual(fake.requests, []) - self.run_once(fake, now=NOW + timedelta(minutes=3)) - self.assertEqual([r[2] for r in fake.requests], ["/issues/search"]) - - def test_r_syncs_now(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - fake.requests.clear() - self.run_once(fake, argv=["--action", "refresh"], now=NOW + timedelta(seconds=30)) - self.assertEqual([r[2] for r in fake.requests], ["/issues/search"]) - - def test_reminders_fire_on_the_minute_between_syncs_after_checking_pylon(self): - # Synced once an hour, and the owner's 20-minute reminder still lands - # at ten minutes in — after asking Pylon whether it's still owed. - env = dict(self.env, **{pylon.SYNC_KEY: "60"}) - fake = _FakePylon(workspace()) - self.run_once(fake, env=env) - self.banners.clear() - fake.requests.clear() - self.run_once(fake, env=env, now=NOW + timedelta(minutes=10)) - self.assertEqual([r[2] for r in fake.requests], ["/issues/search"]) - # Alex's issue breached in the same ten minutes: everyone hears that too. - self.assertEqual(sorted(b[0] for b in self.banners), - ["Pylon #1 · 20m left", "Pylon #2 · first response missed"]) - - def test_an_issue_answered_since_the_last_sync_is_not_reminded_about(self): - env = dict(self.env, **{pylon.SYNC_KEY: "60"}) - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake, env=env) - for issue in routes[("POST", "/issues/search")]["data"]: - issue["first_response_time"] = stamp(NOW + timedelta(minutes=1)) - self.banners.clear() - status, doc = self.run_once(fake, env=env, now=NOW + timedelta(minutes=10)) - self.assertEqual((status, self.banners), (0, [])) - self.assertNotIn("issue-1", [r["id"] for r in doc["rows"]]) - - def test_with_pylon_unreachable_a_due_reminder_still_goes_out(self): - env = dict(self.env, **{pylon.SYNC_KEY: "60"}) - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake, env=env) - routes[("POST", "/issues/search")] = http_error(503) - self.banners.clear() - _, doc = self.run_once(fake, env=env, now=NOW + timedelta(minutes=10)) - self.assertIn("Pylon #1 · 20m left", [b[0] for b in self.banners]) - self.assertIn("sync failed", doc["header"]["title"]) - - def test_a_failed_sync_is_not_retried_in_the_same_run(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - routes[("POST", "/issues/search")] = http_error(503) - fake.requests.clear() - self.banners.clear() - self.run_once(fake, now=NOW + timedelta(minutes=10)) # sync due, and reminders due - self.assertEqual([r[2] for r in fake.requests], ["/issues/search"]) - self.assertIn("Pylon #1 · 20m left", [b[0] for b in self.banners]) - - def test_the_ledger_is_saved_before_any_banner_is_posted(self): - # So a run the host kills after posting can't post them again. - saved = [] - def notifier(*banner): - with open(pylon._state_path) as handle: - saved.append(json.load(handle).get("notified")) - fake = _FakePylon(workspace()) - with mock.patch.object(pylon, "_opener", fake), \ - mock.patch.object(pylon, "_notifier", notifier), \ - mock.patch.dict(os.environ, self.env, clear=True), \ - contextlib.redirect_stdout(io.StringIO()): - pylon.main([], now=NOW) - self.assertTrue(saved) - self.assertEqual(saved[0], {"issue-1": 1, "issue-2": 4, "issue-3": 5}) - - def test_a_failed_sync_keeps_drawing_the_last_snapshot(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - routes[("POST", "/issues/search")] = http_error(429, "rate_limited") - status, doc = self.run_once(fake, now=NOW + timedelta(minutes=3)) - self.assertEqual((status, len(doc["rows"])), (0, 3)) - self.assertEqual(doc["header"]["title"], "Waiting on us · sync failed, retrying") - - def test_the_snapshot_keeps_no_message_bodies(self): - routes = workspace() - routes[("POST", "/issues/search")]["data"][0]["body_html"] = "

the customer's whole message

" - self.run_once(_FakePylon(routes)) - with open(pylon._state_path) as handle: - self.assertNotIn("whole message", handle.read()) - - def test_the_sync_setting_is_read_forgivingly(self): - for raw, minutes in (("", 3), ("abc", 3), ("2.5", 3), ("0", 1), ("999", 60), (" 7 ", 7)): - with mock.patch.dict(os.environ, {pylon.SYNC_KEY: raw}, clear=True): - self.assertEqual(pylon.sync_minutes(), minutes, raw) - - def test_a_failed_user_refresh_keeps_the_last_list(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - routes[("GET", "/users")] = http_error(503) - with mock.patch.object(pylon, "USERS_TTL", 0): - status, doc = self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual(status, 0) - self.assertNotIn("sync failed", doc["header"]["title"]) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertTrue(footnotes["issue-1"].startswith("yours")) - - def test_with_no_user_list_at_all_the_sync_waits_rather_than_guess(self): - routes = workspace() - routes[("GET", "/users")] = http_error(503) - status, doc = self.run_once(_FakePylon(routes)) - self.assertEqual((status, doc), (1, None)) - - def test_a_blocked_read_cannot_outlast_the_host(self): - self.assertLess(pylon.TOTAL_BUDGET + pylon.MAX_PER_REQUEST, pylon.HOST_TIMEOUT) - - def test_a_quiet_ticket_with_engineering_shows_and_pings_nobody(self): - routes = workspace() - routes[("POST", "/issues/search")]["data"].append(issue( - 9, account={"id": "acct-mine"}, state="waiting_on_engineering", - first_response_time=stamp(NOW - timedelta(days=12)), first_response_breach_time=None, - latest_message_time=stamp(NOW - timedelta(days=12)))) - status, doc = self.run_once(_FakePylon(routes)) - rows = {r["id"]: r for r in doc["rows"]} - self.assertEqual(status, 0) - self.assertEqual(rows["issue-9"]["track"]["tint"], pylon.PURPLE) - self.assertEqual(rows["issue-9"]["value"], "quiet 12d") - self.assertEqual([r["id"] for r in doc["rows"]][-1], "issue-9") - self.assertNotIn("Pylon #9", " ".join(b[0] for b in self.banners)) - - # --- Ownership -------------------------------------------------------- - - def test_the_assignee_is_the_owner_and_the_account_owner_stands_in(self): - routes = workspace() - data = routes[("POST", "/issues/search")]["data"] - data[0]["assignee"] = {"id": ALEX} # my account, assigned to Alex - data[1]["assignee"] = {"id": ME} # Alex's account, assigned to me - _, doc = self.run_once(_FakePylon(routes)) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertTrue(footnotes["issue-1"].startswith("Alex")) - self.assertTrue(footnotes["issue-2"].startswith("yours")) - self.assertIn(" · ours", footnotes["issue-3"]) # no preview, so the stage comes first - - def test_an_out_of_office_owners_issues_are_ours(self): - routes = workspace() - routes[("GET", "/users")]["data"][1]["status"] = "out_of_office" - data = routes[("POST", "/issues/search")]["data"] - # Alex's issue, twenty-five minutes left: an owner's stage, so only - # Alex would hear — unless Alex is away. - data[1]["first_response_breach_time"] = stamp(NOW + timedelta(minutes=25)) - data[1]["created_at"] = stamp(NOW - timedelta(minutes=5)) - _, doc = self.run_once(_FakePylon(routes)) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertTrue(footnotes["issue-2"].startswith("ours (Alex away)")) - self.assertIn("Pylon #2 · 25m left", [b[0] for b in self.banners]) - - def test_a_present_owners_early_stages_are_theirs_alone(self): - routes = workspace() - data = routes[("POST", "/issues/search")]["data"] - data[1]["first_response_breach_time"] = stamp(NOW + timedelta(minutes=25)) - data[1]["created_at"] = stamp(NOW - timedelta(minutes=5)) - self.run_once(_FakePylon(routes)) - self.assertNotIn("Pylon #2 · 25m left", [b[0] for b in self.banners]) - - def test_a_preview_cached_before_the_customer_field_is_fetched_again(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - with open(pylon._state_path) as handle: - state = json.load(handle) - for entry in state["previews"].values(): - entry.pop("v", None) - entry.pop("customer", None) - with open(pylon._state_path, "w") as handle: - json.dump(state, handle) - fake.requests.clear() - self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual(sorted(message_calls(fake)), ["issue-1", "issue-2", "issue-3"]) - - def test_a_refused_user_list_keeps_the_last_one(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - routes[("GET", "/users")] = http_error(403, "permission_denied") - with mock.patch.object(pylon, "USERS_TTL", 0): - status, doc = self.run_once(fake, argv=["--action", "refresh"]) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertEqual(status, 0) - self.assertTrue(footnotes["issue-1"].startswith("yours")) - - def test_an_email_that_matches_nobody_is_said_rather_than_guessed(self): - env = dict(self.env, **{pylon.EMAIL_KEY: "nobody@example.com"}) - _, doc = self.run_once(_FakePylon(workspace()), env=env) - self.assertIn("can't find you in Pylon", doc["header"]["title"]) - self.assertNotIn("yours", " ".join(r["footnote"] for r in doc["rows"])) - - # --- Completeness and failure ------------------------------------------- - - def test_pages_are_followed_to_the_end(self): - routes = workspace() - first, second, third = routes[("POST", "/issues/search")]["data"][:3] - pages = {None: {"data": [first], "pagination": {"has_next_page": True, "cursor": "p2"}}, - "p2": {"data": [second, third], "pagination": {"has_next_page": False}}} - routes[("POST", "/issues/search")] = lambda host, body, path: pages[body.get("cursor")] - fake = _FakePylon(routes) - _, doc = self.run_once(fake) - searches = [r[3] for r in fake.requests if r[2] == "/issues/search"] - self.assertEqual([s.get("cursor") for s in searches], [None, "p2"]) - self.assertEqual(searches[0]["limit"], pylon.SEARCH_LIMIT) - self.assertEqual(len(doc["rows"]), 3) - self.assertNotIn("partial", doc["header"]["title"]) - - def test_a_scan_that_cannot_finish_keeps_what_it_did_not_reach(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - reached = routes[("POST", "/issues/search")]["data"][2] - routes[("POST", "/issues/search")] = { - "data": [reached], "pagination": {"has_next_page": True, "cursor": "more"}} - with mock.patch.object(pylon, "MAX_PAGES", 1): - _, doc = self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual(sorted(r["id"] for r in doc["rows"]), ["issue-1", "issue-2", "issue-3"]) - self.assertIn("partial sync", doc["header"]["title"]) - - def test_a_bad_request_keeps_drawing_the_last_snapshot(self): - routes = workspace() - fake = _FakePylon(routes) - self.run_once(fake) - routes[("POST", "/issues/search")] = http_error(400, "invalid_request_body") - status, doc = self.run_once(fake, argv=["--action", "refresh"]) - self.assertEqual((status, len(doc["rows"])), (0, 3)) - self.assertIn("sync failed (Pylon 400)", doc["header"]["title"]) - - def test_a_bad_request_with_nothing_to_show_says_so(self): - routes = workspace() - routes[("POST", "/issues/search")] = http_error(400, "invalid_request_body") - _, doc = self.run_once(_FakePylon(routes)) - self.assertEqual((doc["state"], doc["message"]), ("error", "Pylon returned 400.")) - - def test_a_malformed_snapshot_is_replaced_not_fatal(self): - token = hashlib.sha256(b"secret-token").hexdigest()[:12] - with open(pylon._state_path, "w") as handle: - json.dump({"token": token, "snapshot": {"at": "invalid", "issues": "x"}, - "links": [], "notified": "x", "users": 3}, handle) - status, doc = self.run_once(_FakePylon(workspace())) - self.assertEqual((status, len(doc["rows"])), (0, 3)) - - def test_a_thread_cut_short_is_fetched_again_on_the_next_sync(self): - routes = workspace() - routes[("GET", "/issues/*/messages")] = lambda host, body, path: { - "data": THREADS.get(path.split("/")[2], []), - "pagination": {"has_next_page": True, "cursor": "more"}} - fake = _FakePylon(routes) - with mock.patch.object(pylon, "MESSAGE_PAGES", 1): - _, doc = self.run_once(fake) - footnotes = {r["id"]: r["footnote"] for r in doc["rows"]} - self.assertIn("Robin Vale", footnotes["issue-1"]) - fake.requests.clear() - self.run_once(fake, argv=["--action", "refresh"]) - self.assertIn("issue-1", message_calls(fake)) - - def test_the_state_file_is_readable_only_by_you(self): - stale = pylon._state_path + ".tmp" - with open(stale, "w") as handle: - handle.write("{}") - os.chmod(stale, 0o644) - self.run_once(_FakePylon(workspace())) - self.assertEqual(os.stat(pylon._state_path).st_mode & 0o777, 0o600) - - def test_an_error_body_is_read_only_as_far_as_its_code(self): - class Body: - asked = None - def read(self, size=-1): - Body.asked = size - return b'{"code": "rate_limited"}' - def close(self): - pass - error = urllib.error.HTTPError("https://api.usepylon.com", 429, "busy", {}, Body()) - self.assertEqual(pylon.api_error_code(error), "rate_limited") - self.assertEqual(Body.asked, pylon.ERROR_BODY_BYTES) - error.close() - - def test_a_new_token_forgets_what_the_old_one_learned(self): - fake = _FakePylon(workspace()) - self.run_once(fake) - fake.requests.clear() - self.run_once(fake, env={pylon.TOKEN_KEY: "another-token"}) - self.assertIn("/me", [r[2] for r in fake.requests]) - - -if __name__ == "__main__": - unittest.main() diff --git a/extensions/system/manifest.json b/extensions/system/manifest.json deleted file mode 100644 index 4e3e8aa..0000000 --- a/extensions/system/manifest.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "id": "system", - "name": "System", - "description": "CPU, memory and disk usage at a glance.", - "version": "1.1.1", - "schema": 1, - "tab": { "label": "System" }, - "run": "./run", - "requires": [], - "config": [], - "refresh": { "onOpen": true, "intervalSeconds": 60, "whileFocusedOnly": true } -} diff --git a/extensions/system/run b/extensions/system/run deleted file mode 100755 index 0f3a944..0000000 --- a/extensions/system/run +++ /dev/null @@ -1,225 +0,0 @@ -#!/bin/sh -# -# The reference extension: CPU, memory and disk, each as a row whose bar is the -# used fraction. -# -# There is no chart primitive in the schema, and none is needed here — a -# proportion is what a bar is for. (A sparkline would be expressible as a -# sprite, since that primitive is a grid of coloured cells, but it would mean -# the extension keeping its own history between invocations.) -# -# It is deliberately small and dependency-free — /bin/sh and df, nothing else — -# because its job is to be the thing you read when writing your own. See -# docs/extensions.md for the schema it prints. - -set -eu - -# Colour the bar by how full the volume is. The host clamps whatever it is given -# toward something legible, so these only have to be roughly right. -tint_for() { - if [ "$1" -ge 90 ]; then echo "#E5534B" - elif [ "$1" -ge 75 ]; then echo "#E8A87C" - else echo "#7FD1B9" - fi -} - -# JSON strings have to be escaped even here: a volume can be called anything, -# including something with a quote or a backslash in it. -# Backslash and quote are the obvious two; the control characters are the ones -# that turn a volume name into an unparseable document rather than a wrong one. -# A name can legally contain them, and JSON may not. -# -# Done in awk rather than sed because BSD sed does not understand \x escapes — -# the first attempt at this silently ate the first character of every title. -json_escape() { - printf '%s' "$1" | awk ' - BEGIN { RS = "\0" } - { - gsub(/\\/, "\\\\") - gsub(/"/, "\\\"") - gsub(/\b/, "\\b") - gsub(/\f/, "\\f") - gsub(/\n/, "\\n") - gsub(/\r/, "\\r") - gsub(/\t/, "\\t") - printf "%s", $0 - }' -} - -human() { - awk -v kb="$1" 'BEGIN { - split("KB MB GB TB PB", unit, " ") - i = 1 - while (kb >= 1024 && i < 5) { kb /= 1024; i++ } - printf (kb >= 10 || kb == int(kb)) ? "%.0f%s" : "%.1f%s", kb, unit[i] - }' -} - -rows="" -worst=0 -count=0 -json_rows="" -index=0 - -# A rank would be meaningless here — these are unlike things, not a leaderboard -# — so no row carries a lead. -append_row() { # id _unused title subtitle value footnote fill pct - local_sep="" - [ -n "$json_rows" ] && local_sep="," - subtitle_json="" - [ -z "$4" ] || subtitle_json=$(printf ',"subtitle":"%s"' "$(json_escape "$4")") - json_rows="$json_rows$local_sep$(printf '{"id":"%s","title":"%s"%s,"value":"%s","footnote":"%s","track":{"fill":%s,"tint":"%s"}}' \ - "$1" "$(json_escape "$3")" "$subtitle_json" \ - "$(json_escape "$5")" "$(json_escape "$6")" "$7" "$(tint_for "$8")")" - [ "$8" -gt "$worst" ] && worst="$8" - count=$((count + 1)) -} - -# CPU. ps reports a per-process decaying average, so summing it and dividing by -# the core count is a busy-ness figure rather than an instantaneous sample — -# which is the right shape for a bar, and avoids `top -l 2` costing two seconds -# of the invocation budget for a prettier number. -cores=$(sysctl -n hw.ncpu 2>/dev/null || echo 1) -cpu_pct=$(ps -A -o %cpu= 2>/dev/null | awk -v cores="$cores" ' - {sum += $1} - END { - pct = (cores > 0) ? sum / cores : 0 - if (pct > 100) pct = 100 - printf "%d", pct + 0.5 - } -') -[ -n "$cpu_pct" ] || cpu_pct=0 -append_row cpu "" "CPU" "$cores cores" "$cpu_pct%" "across all cores" \ - "$(awk -v p="$cpu_pct" 'BEGIN {printf "%.4f", p / 100}')" "$cpu_pct" - -# Memory. vm_stat counts pages, so the page size comes from its own header -# rather than being assumed — it is 16K on Apple silicon and 4K on Intel. -mem_total=$(sysctl -n hw.memsize 2>/dev/null || echo 0) -if [ "$mem_total" -gt 0 ]; then - mem_used=$(vm_stat 2>/dev/null | awk ' - /page size of/ { for (i = 1; i <= NF; i++) if ($i == "of") page = $(i+1) } - /^Pages active/ { active = $3 } - /^Pages wired down/ { wired = $4 } - /^Pages occupied by compressor/ { compressed = $5 } - END { - gsub(/\./, "", active); gsub(/\./, "", wired); gsub(/\./, "", compressed) - # Print nothing rather than zero when the header or the fields are - # missing. vm_stat absent, or reformatted, otherwise multiplied by an - # unset page size and reported a confident "0% used, all free" — - # which is worse than saying nothing, because it looks like an answer. - if (page > 0 && active != "" && wired != "") { - # Active + wired + compressed is what macOS itself counts as - # used: inactive pages are reclaimable and counting them reads - # as a leak. - printf "%.0f", (active + wired + compressed) * page - } - } - ') - # No usable reading means no memory row, the same way a volume reporting a - # zero total is skipped rather than drawn as empty. - if [ -n "$mem_used" ] && [ "$mem_used" -gt 0 ] 2>/dev/null; then - mem_pct=$(awk -v u="$mem_used" -v t="$mem_total" 'BEGIN {printf "%d", (u * 100 / t) + 0.5}') - mem_free_label=$(human "$(awk -v u="$mem_used" -v t="$mem_total" 'BEGIN {printf "%d", (t - u) / 1024}')") - append_row mem "" "Memory" "$(human "$(awk -v t="$mem_total" 'BEGIN {printf "%d", t / 1024}')") installed" \ - "$mem_free_label free" "$mem_pct% used" \ - "$(awk -v p="$mem_pct" 'BEGIN {printf "%.4f", p / 100}')" "$mem_pct" - fi -fi - -# -P for POSIX output (one line per filesystem, never wrapped); -k for KiB so -# the arithmetic below is in one unit. Local volumes only — a stalled network -# mount would otherwise hang df and take the whole pane's budget with it. -df_output=$(df -Pkl 2>/dev/null) || df_output="" - -if [ -z "$df_output" ]; then - printf '{"schema":1,"state":"error","message":"df returned nothing"}\n' - exit 0 -fi - -# Parsed in awk rather than a shell loop so the arithmetic is one pass and the -# fields are split the same way every time. -rows=$(printf '%s\n' "$df_output" | tail -n +2 | awk ' - { - # Mount point is everything from field 6 onward — a path can contain - # spaces, and "Volumes/My Disk" is ordinary on a Mac. - mount = $6 - for (i = 7; i <= NF; i++) mount = mount " " $i - if (mount == "") next - - # macOS mounts a handful of synthetic volumes that all report the same - # underlying container, so listing them is seven rows of noise around - # the one number anybody wants. - if (mount ~ /^\/System\/Volumes\// && mount != "/System/Volumes/Data") next - if (mount ~ /^\/(dev|private\/var\/vm)$/) next - - # An APFS boot drive is split across a read-only system volume at "/" - # and a Data volume, sharing one container. Reporting both is what makes - # the pane say 440GB free twice at two different percentages — true, and - # unreadable. The startup disk is one thing to the person looking at it, - # so Data carries it and "/" is dropped. - if (mount == "/") next - - total = $2 + 0 - used = $3 + 0 - avail = $4 + 0 - if (total <= 0) next - - pct = used * 100 / total - fill = used / total - - name = mount - sub(/.*\//, "", name) - if (name == "") name = "/" - if (mount == "/System/Volumes/Data") { name = "Startup disk"; mount = "/" } - - printf "%s\t%s\t%.4f\t%d\t%d\n", name, mount, fill, pct, avail - } -') - -# No reportable volume is not an empty pane: the CPU and memory rows were -# computed a moment ago and discarding them was throwing away the two thirds of -# this extension that had worked. -if [ -z "$rows" ] && [ -z "$json_rows" ]; then - printf '{"schema":1,"state":"empty","message":"Nothing to report"}\n' - exit 0 -fi - -while IFS="$(printf '\t')" read -r name mount fill pct avail; do - [ -n "$name" ] || continue - index=$((index + 1)) - [ "$pct" -gt "$worst" ] && worst=$pct - count=$((count + 1)) - - free_label=$(human "$avail") - tint=$(tint_for "$pct") - sep="" - [ -n "$json_rows" ] && sep="," - - # A subtitle that repeats the title is noise, which is what "/ /" was. - subtitle="" - [ "$mount" = "$name" ] || subtitle=$(printf ',"subtitle":"%s"' "$(json_escape "$mount")") - - json_rows="$json_rows$sep$(printf '{"id":"v%s","title":"%s"%s,"value":"%s free","footnote":"%s%% used","track":{"fill":%s,"tint":"%s"}}' \ - "$index" \ - "$(json_escape "$name")" \ - "$subtitle" \ - "$free_label" \ - "$pct" \ - "$fill" \ - "$tint")" -done </dev/null || true)" - else - manifest="$(git show "$1:$2/manifest.json" 2>/dev/null || true)" - fi - [[ -n "$manifest" ]] || return 0 - printf '%s' "$manifest" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("version",""))' -} - -rc=0 -checked=0 -for dir in extensions/*/; do - dir="${dir%/}" - id="$(basename "$dir")" - - # Nothing touched in this extension: nothing to require. - # - # Untracked files count. A new test or helper dropped into an extension - # directory is invisible to `git diff` and still ends up in the tarball the - # index checksums, so skipping on the diff alone let exactly the change this - # check exists for walk past it locally. - untracked="$(git ls-files --others --exclude-standard -- "$dir")" - if git diff --quiet "$merge_base" -- "$dir" && [[ -z "$untracked" ]]; then - continue - fi - checked=$((checked + 1)) - - before="$(version_at "$merge_base" "$dir")" - after="$(version_at "" "$dir")" - - # A brand new extension has no previous version to differ from. - if [[ -z "$before" ]]; then - echo " ✓ $id is new at $after" - continue - fi - - if [[ "$before" == "$after" ]]; then - echo " ✗ $id changed but its version is still $after" >&2 - echo " Bump \"version\" in $dir/manifest.json. The app offers an update" >&2 - echo " only when the published version differs from the installed one," >&2 - echo " so republishing under $after reaches nobody who already has it." >&2 - rc=1 - else - echo " ✓ $id $before → $after" - fi -done - -if [[ "$checked" -eq 0 ]]; then - echo "no extension changed against ${base}" -fi -exit "$rc" diff --git a/scripts/package-extensions.sh b/scripts/package-extensions.sh deleted file mode 100755 index a4e1165..0000000 --- a/scripts/package-extensions.sh +++ /dev/null @@ -1,472 +0,0 @@ -#!/usr/bin/env bash -# -# Validate and package the extensions under extensions/ for a release. -# -# scripts/package-extensions.sh validate # CI gate, on every PR -# scripts/package-extensions.sh package [outdir] -# -# Validation is the curation gate doing real work. An extension PR is reviewed -# as code, but a reviewer reads a diff — and a diff does not show where a symlink -# points. A tarball carries symlinks perfectly well, so without this an approved -# manifest can say one thing and the package do another. The host refuses an -# escaping run path at spawn time, but by then the review has already happened. -# -# Packaging mirrors the app's own convention (release.yml): .tar.gz plus a -# .tar.gz.sha256 sidecar holding " ". The app refuses to -# install anything whose sidecar is missing, so the sidecar is not optional. - -set -euo pipefail - -repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -ext_root="$repo_root/extensions" -# Which tier each extension is reviewed for: view, service or trusted. Owned by -# the reviewers rather than by the extensions, so a manifest can't promote -# itself; the index carries it to the host, which records it at install. An -# extension missing from it is `view`. See docs/design/service-extensions.md, -# "Privilege tiers". -tiers_file="$ext_root/tiers.json" - -mode="${1:-validate}" -outdir="${2:-$repo_root/dist/extensions}" - -fail() { - echo " ✗ $1" >&2 - return 1 -} - -# Every path inside a package must be a regular file or a directory. Symlinks are -# the point of this check; device nodes, sockets and fifos are refused for the -# same reason, which is that nothing legitimate needs them and a tar can carry -# them. -validate_tree() { - local dir="$1" id="$2" rc=0 - local entries=() - while IFS= read -r -d '' entry; do - entries+=("$entry") - done < <(find "$dir" -mindepth 1 -print0) - - for entry in ${entries[@]+"${entries[@]}"}; do - local rel="${entry#"$dir"/}" - if [[ -L "$entry" ]]; then - fail "$id: '$rel' is a symlink -> $(readlink "$entry")" || rc=1 - elif [[ ! -f "$entry" && ! -d "$entry" ]]; then - fail "$id: '$rel' is not a regular file or directory" || rc=1 - fi - done - return "$rc" -} - -# The manifest is read with python3 rather than jq: jq is not guaranteed on a -# runner, python3 is already a hard dependency of notify.sh. -manifest_field() { - python3 -c ' -import json, sys -with open(sys.argv[1]) as fh: - print(json.load(fh).get(sys.argv[2], "")) -' "$1" "$2" -} - -# The capabilities the host knows, read from the ExtensionCapability enum -# itself so the check can't drift from it. Each `case` line in the enum's own -# block gives one: its raw value if it spells one out (`case eventIdle = -# "event:idle"`), otherwise its name (`case feed`). Finding no enum or no cases -# is an error, so a refactor that moves or reshapes the enum fails the gate -# loudly instead of quietly checking against nothing. -capability_source="$repo_root/panel/ExtensionManifest.swift" -known_capabilities() { - python3 - "$capability_source" <<'PY' -import re, sys -try: - text = open(sys.argv[1]).read() -except OSError as e: - sys.exit(f"can't read {sys.argv[1]}: {e}") -# Block comments go first, keeping their line breaks, so a case commented out -# with /* */ isn't counted as known. Line comments are cut per line below. -text = re.sub(r"/\*.*?\*/", lambda m: "\n" * m.group(0).count("\n"), text, flags=re.S) -lines = text.splitlines() -start = next((i for i, l in enumerate(lines) - if re.match(r"\s*(?:\w+\s+)*enum\s+ExtensionCapability\b", l)), None) -if start is None: - sys.exit(f"no `enum ExtensionCapability` in {sys.argv[1]}") -depth, opened, found = 0, False, [] -for line in lines[start:]: - code = line.split("//", 1)[0] - # Only the enum's own level: a `case` inside a nested switch isn't one. - if depth == 1: - m = re.match(r"\s*case\s+(.*?)\s*$", code) - if m: - for item in m.group(1).split(","): - c = re.fullmatch(r'\s*(\w+)\s*(?:=\s*"([^"]*)")?\s*', item) - if not c: - sys.exit(f"can't read `{line.strip()}` in {sys.argv[1]}") - found.append(c.group(2) if c.group(2) is not None else c.group(1)) - depth += code.count("{") - code.count("}") - opened = opened or "{" in code - if opened and depth <= 0: - break -if not found: - sys.exit(f"`enum ExtensionCapability` in {sys.argv[1]} has no cases") -print("\n".join(found)) -PY -} - -validate_one() { - local dir="$1" rc=0 - local id manifest run_rel run_path declared_id schema mode version - - id="$(basename "$dir")" - manifest="$dir/manifest.json" - - if [[ ! -f "$manifest" ]]; then - fail "$id: no manifest.json" - return 1 - fi - if ! python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$manifest" 2>/dev/null; then - fail "$id: manifest.json is not valid JSON" - return 1 - fi - - # The directory name is what every path and every tab id is built from, so a - # manifest claiming a different id would let one extension answer to another's. - declared_id="$(manifest_field "$manifest" id)" - [[ "$declared_id" == "$id" ]] || fail "$id: manifest declares id '$declared_id'" || rc=1 - - # Mirrors ExtensionManifest.isValidID — it becomes a directory name, and a - # tar operand, so it may not begin with a dash. - [[ "$id" =~ ^[a-z0-9][a-z0-9-]{0,31}$ ]] \ - || fail "$id: id is not ^[a-z0-9][a-z0-9-]{0,31}\$" || rc=1 - - # Mirrors ExtensionManifest.supportedManifestSchemas: 1 for a view, 2 for - # anything that needs service mode (a view may say 2 as well). Service mode - # on 1 is refused because an older host reads 1 and would run it as a view. - schema="$(manifest_field "$manifest" schema)" - mode="$(manifest_field "$manifest" mode)" - [[ "$schema" == "1" || "$schema" == "2" ]] \ - || fail "$id: schema is '$schema', expected 1 or 2" || rc=1 - case "$mode" in - ""|view) ;; - service) [[ "$schema" == "2" ]] || fail "$id: mode 'service' needs schema 2" || rc=1 ;; - *) fail "$id: unknown mode '$mode'" || rc=1 ;; - esac - - # Against ExtensionCapability: the host refuses a manifest naming anything - # else, so a typo here would ship an extension no host will load. Caught in - # CI instead. - local bad_capability - bad_capability="$(python3 -c ' -import json, sys -known = set(sys.argv[2].split("\n")) -caps = json.load(open(sys.argv[1])).get("capabilities", []) -if not isinstance(caps, list): - print("(not a list)") -else: - for c in caps: - if not isinstance(c, str) or c not in known: - print(c) - break -' "$manifest" "$capabilities")" - [[ -z "$bad_capability" ]] \ - || fail "$id: unknown capability '$bad_capability'" || rc=1 - - # Mirrors ExtensionManifest's surfaces and ConfigKind.read: where it appears, - # and what each typed config key may hold. The host refuses a manifest that - # gets either wrong, so CI does too. - local shape_problem - shape_problem="$(python3 -c ' -import json, sys -m = json.load(open(sys.argv[1])) -def say(msg): - print(msg); sys.exit() -surfaces = m.get("surfaces", ["tab"]) -if not isinstance(surfaces, list) or not surfaces: - say("surfaces must be a non-empty list of \"tab\" and \"settings\"") -for s in surfaces: - if s not in ("tab", "settings"): - say("unknown surface %r" % (s,)) -def storable(v): - return isinstance(v, str) and v != "" and len(v) <= 256 and v == v.strip() \ - and not any(ord(c) < 32 or ord(c) == 127 for c in v) -for entry in m.get("config", []): - if not isinstance(entry, dict): - continue - key, kind = entry.get("key"), entry.get("type", "text") - opts = entry.get("options") - if kind in ("text", "toggle", "dynamic"): - if opts is not None: - say("config key %s is type %s, which takes no options" % (key, kind)) - elif kind == "choice": - if not isinstance(opts, list) or not opts or len(opts) > 64: - say("config key %s is a choice and needs 1 to 64 {value, label} options" % key) - values = [o.get("value") if isinstance(o, dict) else None for o in opts] - if len(set(map(str, values))) != len(values): - say("config key %s lists the same option twice" % key) - for o in opts: - if not storable(o.get("value")) or not isinstance(o.get("label"), str) or not o["label"]: - say("config key %s has an option that cannot be stored or shown" % key) - elif kind == "number": - if not isinstance(opts, list) or not opts or len(opts) > 64 \ - or not all(isinstance(n, int) and not isinstance(n, bool) for n in opts): - say("config key %s is a number and needs 1 to 64 whole-number options" % key) - if len(set(opts)) != len(opts): - say("config key %s lists the same number twice" % key) - if entry.get("unit") not in (None, "seconds"): - say("config key %s has unknown unit %r" % (key, entry.get("unit"))) - else: - say("config key %s has unknown type %r" % (key, kind)) -' "$manifest")" - [[ -z "$shape_problem" ]] || fail "$id: $shape_problem" || rc=1 - - # Mirrors ExtensionTier.allows. An extension asking for more than its tier - # grants would install and then run without it (or, in service mode below - # the service tier, not run at all), so the mismatch is a CI failure rather - # than something a user finds out. - local tier_problem - tier_problem="$(python3 -c ' -import json, sys -manifest = json.load(open(sys.argv[1])) -try: - tiers = json.load(open(sys.argv[2])) -except FileNotFoundError: - tiers = {} -tier = tiers.get(sys.argv[3], "view") if isinstance(tiers, dict) else "view" -rank = {"view": 0, "service": 1, "trusted": 2} -needs = {"event:idle": 1, "event:panel": 1, "feed": 1, - "signal:presence": 2, "event:session": 2, "event:nudge": 2, "bluetooth": 2} -have = rank.get(tier, 0) -if manifest.get("mode") == "service" and have < 1: - print("mode \"service\" needs the service tier; tiers.json gives it %s" % tier) -else: - caps = manifest.get("capabilities", []) - for c in caps if isinstance(caps, list) else []: - if needs.get(c, 0) > have: - print("asks for %s, which tier %s does not grant" % (c, tier)) - break -' "$manifest" "$tiers_file" "$id")" - [[ -z "$tier_problem" ]] || fail "$id: $tier_problem" || rc=1 - - # Constrained like the id is. It becomes part of an asset filename and is - # interpolated into shell, so "non-empty" was never a sufficient check. - version="$(manifest_field "$manifest" version)" - if [[ -z "$version" ]]; then - fail "$id: no version" || rc=1 - elif [[ ! "$version" =~ ^[0-9A-Za-z][0-9A-Za-z.+-]{0,31}$ ]]; then - fail "$id: version '$version' is not ^[0-9A-Za-z][0-9A-Za-z.+-]{0,31}\$" || rc=1 - fi - - run_rel="$(manifest_field "$manifest" run)" - [[ -n "$run_rel" ]] || run_rel="./run" - case "$run_rel" in - /*|~*) fail "$id: run '$run_rel' is absolute" || rc=1 ;; - *..*) fail "$id: run '$run_rel' escapes the package" || rc=1 ;; - esac - - run_path="$dir/${run_rel#./}" - if [[ ! -e "$run_path" ]]; then - fail "$id: run '$run_rel' does not exist" || rc=1 - elif [[ -L "$run_path" ]]; then - fail "$id: run '$run_rel' is a symlink" || rc=1 - elif [[ ! -f "$run_path" ]]; then - fail "$id: run '$run_rel' is not a regular file" || rc=1 - elif [[ ! -x "$run_path" ]]; then - fail "$id: run '$run_rel' is not executable" || rc=1 - fi - - validate_tree "$dir" "$id" || rc=1 - - [[ "$rc" -eq 0 ]] && echo " ✓ $id $version" - return "$rc" -} - -# Namespaced so an extension asset can never be mistaken for the app's own: they -# share a release, and the updater picks its download by name. Defined once, -# because the packer and the index both need it and a disagreement between them -# is a sidecar that verifies nothing. -asset_name() { printf 'extension-%s-%s.tar.gz' "$1" "$2"; } - -package_one() { - local dir="$1" id version asset - id="$(basename "$dir")" - version="$(manifest_field "$dir/manifest.json" version)" - asset="$(asset_name "$id" "$version")" - - # -C so the archive root is the id directory, matching what the installer - # expects to find after extraction. - # -- so an id can never be read as an option, belt and braces alongside the - # validator's leading-dash rule. - # - # Python bytecode is excluded because the package is built from the working - # tree, not from git: an extension with tests leaves __pycache__ behind the - # first time anyone runs them, and the packer swept it in. That shipped stale - # machine-specific .pyc files to every user, and made the tarball's bytes - # depend on whether the person building it had run the tests — which is not a - # thing a checksummed artefact may depend on. - # - # .build is excluded for the same reason: an extension that compiles itself - # on first run (away) keeps its build there, and a binary from whoever ran - # it last has no place in a package whose point is that the source is what - # runs. - tar czf "$outdir/$asset" \ - --exclude '__pycache__' --exclude '*.pyc' --exclude '.DS_Store' --exclude '.build' \ - -C "$ext_root" -- "$id" - # Run from $outdir with a bare basename, shasum already prints exactly - # " " — so there is nothing for awk to do, and no program - # text for a manifest value to reach. The awk that used to be here was - # arbitrary code execution in a job holding contents: write. - ( cd "$outdir" && shasum -a 256 "$asset" > "$asset.sha256" ) - echo " → $asset" -} - -# tiers.json is optional, but if it's there it has to say something the host -# can read: an object of extension ids to a known tier, naming only extensions -# that exist. A typo'd id would otherwise leave its extension at `view` with -# nothing to say why. -validate_tiers() { - [[ -f "$tiers_file" ]] || return 0 - local problem - problem="$(python3 -c ' -import json, os, sys -path, root = sys.argv[1], sys.argv[2] -try: - tiers = json.load(open(path)) -except ValueError: - print("is not valid JSON"); sys.exit() -if not isinstance(tiers, dict): - print("is not an object"); sys.exit() -for ext_id, tier in sorted(tiers.items()): - if tier not in ("view", "service", "trusted"): - print("gives %s the unknown tier %r" % (ext_id, tier)); break - if not os.path.isdir(os.path.join(root, ext_id)): - print("names %s, which is not an extension here" % ext_id); break -' "$tiers_file" "$ext_root")" - if [[ -n "$problem" ]]; then - fail "tiers.json $problem" - return 1 - fi -} - -extension_dirs() { - [[ -d "$ext_root" ]] || return 0 - find "$ext_root" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z -} - -# Enumeration failing must not read as "nothing to validate". A process -# substitution does not propagate its status — pipefail does not reach inside -# one and nothing checked it — so an unreadable extensions/ turned the curation -# gate into a green check with a find error scrolled past above it. -list_extension_dirs() { - if [[ -d "$ext_root" ]] && ! find "$ext_root" -mindepth 1 -maxdepth 1 -type d > /dev/null; then - echo "cannot read $ext_root" >&2 - return 1 - fi - extension_dirs -} - -main() { - local dirs=() rc=0 capabilities - while IFS= read -r -d '' dir; do - dirs+=("$dir") - done < <(list_extension_dirs) - # The subshell's failure is invisible to the loop, so ask again. - if [[ -d "$ext_root" ]] && ! find "$ext_root" -mindepth 1 -maxdepth 1 -type d > /dev/null 2>&1; then - echo "refusing to $mode: cannot read $ext_root" >&2 - return 1 - fi - - # Read once, up front, and before anything else can pass: a gate that - # couldn't read the list must not go on to say every manifest is fine. - if ! capabilities="$(known_capabilities)" || [[ -z "$capabilities" ]]; then - echo "refusing to $mode: couldn't read the capabilities from $capability_source" >&2 - return 1 - fi - - if [[ "${#dirs[@]}" -eq 0 ]]; then - # Not an error. Until the first extension lands, a release still publishes an - # empty index so the app has something well-formed to fetch. - echo "no extensions to $mode" - [[ "$mode" == "package" ]] || return 0 - fi - - case "$mode" in - validate) - echo "validating ${#dirs[@]} extension(s)" - validate_tiers || rc=1 - for dir in ${dirs[@]+"${dirs[@]}"}; do - validate_one "$dir" || rc=1 - done - ;; - package) - validate_tiers || rc=1 - for dir in ${dirs[@]+"${dirs[@]}"}; do - validate_one "$dir" || rc=1 - done - [[ "$rc" -eq 0 ]] || { echo "refusing to package: validation failed" >&2; return 1; } - - mkdir -p "$outdir" - for dir in ${dirs[@]+"${dirs[@]}"}; do - # Without this a tar failure printed an error and the job still exited - # 0, publishing a release that looked successful and was not. - package_one "$dir" || { echo "failed to package $dir" >&2; return 1; } - done - write_index "${dirs[@]+"${dirs[@]}"}" - echo " → extensions-index.json" - ;; - *) - echo "usage: $0 [validate|package] [outdir]" >&2 - return 2 - ;; - esac - return "$rc" -} - -# The index is what the app fetches to know what is installable. Written by -# python3 so the JSON is actually encoded rather than string-concatenated. -write_index() { - python3 - "$outdir" "$tiers_file" "$@" <<'PY' -import hashlib, json, os, sys - -outdir, tiers_file, dirs = sys.argv[1], sys.argv[2], sys.argv[3:] -try: - with open(tiers_file) as fh: - tiers = json.load(fh) -except FileNotFoundError: - tiers = {} -entries = [] -for d in dirs: - with open(os.path.join(d, "manifest.json")) as fh: - m = json.load(fh) - asset = "extension-{}-{}.tar.gz".format(m["id"], m["version"]) - with open(os.path.join(outdir, asset), "rb") as fh: - digest = hashlib.sha256(fh.read()).hexdigest() - entries.append({ - "id": m["id"], - "name": m.get("name", m["id"]), - "version": m["version"], - "description": m.get("description", ""), - "asset": asset, - "sha256": digest, - "requires": m.get("requires", []), - # Key names only. A manifest entry may be an object carrying a label - # and help text, but the index is read by binaries of every version — - # it is fetched from /releases/latest, so an old host reads the newest - # index — and nothing downstream needs the metadata here: the settings - # form renders for an *installed* extension and reads its manifest. - "config": [c["key"] if isinstance(c, dict) else c for c in m.get("config", [])], - # From tiers.json, never the manifest. Hosts that predate tiers ignore - # the field; newer ones record it at install and re-check it on every - # fetch, so lowering it here demotes installed copies. - "tier": tiers.get(m["id"], "view"), - # What it asks for, so the install confirmation can say so before - # anything is downloaded. Additive: older hosts ignore it. - "capabilities": m.get("capabilities", []), - # And how it runs, which decides what the confirmation may claim. - "mode": m.get("mode", "view"), - }) - -entries.sort(key=lambda e: e["id"]) -with open(os.path.join(outdir, "extensions-index.json"), "w") as fh: - json.dump({"schema": 1, "extensions": entries}, fh, indent=2, sort_keys=True) - fh.write("\n") -PY -} - -main "$@" diff --git a/scripts/test-extensions.sh b/scripts/test-extensions.sh deleted file mode 100755 index a03261d..0000000 --- a/scripts/test-extensions.sh +++ /dev/null @@ -1,50 +0,0 @@ -#!/usr/bin/env bash -# -# Run the reference extensions' own test suites. -# -# They are Python rather than XCTest because the extensions are: nothing in an -# extension is Swift, and a script's tests belong beside the script. They also -# ship inside the package deliberately — these are what somebody reads when -# writing their own extension, and "how do I test one of these?" is a question -# the reference should answer. -# -# A suite that discovers zero tests is a failure, not a pass. Discovery -# silently finding nothing is how this repo's Swift harness went a whole PR -# without calling setUpWithError, and every filesystem fixture in it passed by -# never running. - -set -euo pipefail - -repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -cd "$repo_root" - -# Keeps __pycache__ out of the extension directories. The packager excludes it -# anyway, but a directory that grows bytecode the first time anyone runs the -# tests is a working tree that differs from a fresh checkout for no reason. -export PYTHONDONTWRITEBYTECODE=1 - -ran=0 -for dir in extensions/*/; do - compgen -G "${dir}test_*.py" > /dev/null || continue - echo "→ ${dir}" - # `if !` rather than a bare assignment: under `set -e` the shell dies at the - # assignment itself when the command substitution fails, so the echo below it - # never ran and a failing suite went red in CI with no output at all — - # nothing naming the test, the assertion or the file. - if ! output="$(python3 -m unittest discover -s "$dir" -t "$dir" -p 'test_*.py' 2>&1)"; then - echo "$output" - echo "tests failed in $dir" >&2 - exit 1 - fi - echo "$output" - if ! grep -qE '^Ran [1-9][0-9]* tests?' <<< "$output"; then - echo "no tests ran in $dir" >&2 - exit 1 - fi - ran=$((ran + 1)) -done - -if [[ "$ran" -eq 0 ]]; then - echo "no extension test suites found" >&2 - exit 1 -fi