Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 26 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ The key is the project's public key: the 32 hex characters at the start of the p
(`https://<key>@kestrel.example.com/1`), on the project's settings page in Kestrel. It's the same key
the Sentry SDK uses, so one project gets both errors and analytics.

KestrelKit only talks to `https://` addresses. `http://` works for `localhost`, and in debug builds
for any host (a Kestrel on your own network); in a release build any other `http://` address is
refused and nothing is stored or sent.

### SwiftUI

```swift
Expand Down Expand Up @@ -117,12 +121,21 @@ Each signal has:
**Never collected:** the IDFA or IDFV, the device name, the user's name or email, location, contacts,
IP addresses (Kestrel doesn't store them), or anything to fingerprint a device.

Payloads are filtered on the device, with the same rules Kestrel applies again on the server:
Payloads are filtered on the device, with the same rules Kestrel applies again on the server (the
shortened IPv6 forms and the dot and non-breaking-space card groupings below are only caught on the
device for now). Control characters are removed first, and a value is cut to 2,000 characters before
it is filtered, so a very long value is cheap:

- values that look like an email address, a phone number, a card number, an IP address, a
`Bearer`/`Basic` credential or a `token=…`-style secret are replaced by `[Filtered]`;
- values that look like an email address, a phone number, a card number (13 to 19 digits grouped by
spaces, dashes, dots or non-breaking spaces, and passing the Luhn check), an IP address (IPv4, and
IPv6 written out or shortened with `::`, such as `2001:db8::1` and `::1`), a `Bearer`/`Basic`
credential or a `token=…`-style secret are replaced by `[Filtered]`;
- keys that name an IP address or a user agent (`ip`, `client_ip`, `x-forwarded-for`, `user_agent`
and the like) are dropped with their values.
and the like) are dropped with their values;
- keys that look like they hold a secret are dropped with their values: any key containing `pass`
(`password`, `passwd`), `secret`, `token`, `auth`, `key`, `card`, `cookie` or `cvv`, and `ssn` as a
word of its own, ignoring case. This is blunt on purpose: `keyboard_layout` and `author` go too, so
give such keys other names (`layout`, `writer`).

Payloads are limited to 20 keys of up to 40 characters, with values of up to 200 characters. Keep
personal data out of them; the filtering is a safety net, not a licence.
Expand Down Expand Up @@ -157,8 +170,15 @@ choice across launches. Nothing is sent before `Kestrel.configure` is called eit
survive restarts and offline periods. Each batch holds up to 100 signals or 256 KB, and is
gzipped when that makes it smaller.
- When the server is busy or unreachable, KestrelKit backs off: from 30 seconds up to an hour, or as
long as the server's `Retry-After` says. A wrong or disabled key stops sending until the next
launch.
long as the server's `Retry-After` says. A wrong or disabled key (or a server without app
analytics) pauses sending for an hour. Only Keen Kestrel's own answer (`202` with `{"accepted": n}`)
counts as delivered; any other answer, a captive portal's `200` for example, keeps the batch and
retries with backoff.
- Redirects are never followed, answers bigger than 64 KB are ignored, and a request gets 60 seconds
at most.
- Turning `Kestrel.isEnabled` off cancels an upload in progress and sends nothing more.
- Up to 1,000 calls can wait for the queue at once while it is busy; when more arrive, the oldest are
dropped.
- On iOS, tvOS and visionOS, KestrelKit asks for a little background time to finish the upload when
the app moves to the background. On the Mac, "background" means another app is active.
- TestFlight builds are recognised by their sandbox App Store receipt. This doesn't work for Mac
Expand Down
66 changes: 51 additions & 15 deletions Sources/KestrelKit/Client.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,18 @@ enum Command: Sendable {
case foreground(time: Date)
case optOut
case barrier(CheckedContinuation<Void, Never>)

/// Lets whoever waits for this command go, for a command that will never be handled.
func abandon() {
switch self {
case let .flush(done), let .barrier(done):
done.resume()
case let .background(_, done):
done?.resume()
case .signal, .tick, .foreground, .optOut:
break
}
}
}

/// The outside world, swappable in tests.
Expand Down Expand Up @@ -39,12 +51,13 @@ struct Environment: Sendable {

let configuration = URLSessionConfiguration.ephemeral
configuration.timeoutIntervalForRequest = 30
configuration.timeoutIntervalForResource = 60
configuration.httpCookieStorage = nil
configuration.urlCache = nil
return Environment(
store: store,
directory: directory,
session: URLSession(configuration: configuration),
session: TransportDelegate.makeSession(configuration),
device: device
)
}
Expand All @@ -53,23 +66,29 @@ struct Environment: Sendable {
/// One configured KestrelKit: takes calls from any thread without blocking and hands them,
/// in order, to the ``Engine`` actor through an `AsyncStream`.
final class Client: Sendable {
/// The most commands waiting for the engine. When the engine is stuck (a slow network
/// call, say) and an app sends signals faster than that, the oldest commands go first.
static let maxPendingCommands = 1_000

let configuration: Kestrel.Configuration
let environment: Environment
private let continuation: AsyncStream<Command>.Continuation
private let uploader: Uploader
private let timer: Task<Void, Never>?

init(baseURL: URL, key: String, configuration: Kestrel.Configuration, environment: Environment) {
self.configuration = configuration
self.environment = environment

let (stream, continuation) = AsyncStream.makeStream(of: Command.self)
let (stream, continuation) = AsyncStream.makeStream(
of: Command.self,
bufferingPolicy: .bufferingNewest(Self.maxPendingCommands)
)
self.continuation = continuation

let engine = Engine(
uploader: Uploader(endpoint: Uploader.endpoint(for: baseURL), key: key, session: environment.session),
configuration: configuration,
environment: environment
)
let uploader = Uploader(endpoint: Uploader.endpoint(for: baseURL), key: key, session: environment.session)
self.uploader = uploader
let engine = Engine(uploader: uploader, configuration: configuration, environment: environment)
Task {
for await command in stream {
await engine.handle(command)
Expand All @@ -82,7 +101,7 @@ final class Client: Sendable {
while !Task.isCancelled {
try? await Task.sleep(nanoseconds: UInt64(interval * 1_000_000_000))
if Task.isCancelled { break }
if case .terminated = continuation.yield(.tick) { break }
if case .terminated = Self.enqueue(.tick, on: continuation) { break }
}
}
} else {
Expand All @@ -91,9 +110,9 @@ final class Client: Sendable {

if !environment.store.isEnabled {
// Opted out in an earlier run: make sure nothing is left behind.
continuation.yield(.optOut)
Self.enqueue(.optOut, on: continuation)
} else if configuration.automaticSignals {
continuation.yield(.signal(type: "App.launched", payload: [:], time: environment.now()))
Self.enqueue(.signal(type: "App.launched", payload: [:], time: environment.now()), on: continuation)
}
}

Expand All @@ -107,7 +126,7 @@ final class Client: Sendable {

func signal(_ type: String, payload: [String: String] = [:]) {
guard isEnabled else { return }
continuation.yield(.signal(type: type, payload: payload, time: environment.now()))
Self.enqueue(.signal(type: type, payload: payload, time: environment.now()), on: continuation)
}

func flush() async {
Expand All @@ -122,12 +141,14 @@ final class Client: Sendable {

/// The app is back: a new session starts if it was away for 5 minutes or more.
func willEnterForeground() {
continuation.yield(.foreground(time: environment.now()))
Self.enqueue(.foreground(time: environment.now()), on: continuation)
}

/// Deletes the queue and the install id.
/// Deletes the queue and the install id, and stops the upload in flight at once. The engine
/// is busy while it waits for the server, so the opt-out can't wait for its turn.
func optOut() {
continuation.yield(.optOut)
uploader.control.cancel()
Self.enqueue(.optOut, on: continuation)
}

/// Returns once everything sent to the engine before it has been handled.
Expand All @@ -140,9 +161,24 @@ final class Client: Sendable {
continuation.finish()
}

/// Hands a command to the engine. When the stream is full, the oldest command is dropped:
/// its waiter is let go, and an opt-out is put back, because that one must not get lost.
@discardableResult
static func enqueue(
_ command: Command,
on continuation: AsyncStream<Command>.Continuation
) -> AsyncStream<Command>.Continuation.YieldResult {
let result = continuation.yield(command)
guard case let .dropped(oldest) = result else { return result }
oldest.abandon()
guard case .optOut = oldest else { return result }
if case .optOut = command { return result }
return enqueue(oldest, on: continuation)
}

private func send(_ command: (CheckedContinuation<Void, Never>) -> Command) async {
await withCheckedContinuation { done in
if case .terminated = continuation.yield(command(done)) {
if case .terminated = Self.enqueue(command(done), on: continuation) {
done.resume()
}
}
Expand Down
42 changes: 29 additions & 13 deletions Sources/KestrelKit/DiskQueue.swift
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,35 @@ import Foundation
/// Signals waiting to be sent, kept in memory and mirrored to a JSON-lines file
/// (`signals.jsonl`, one encoded signal per line) so they survive restarts.
///
/// New signals are appended to the file; sending or dropping signals rewrites it
/// atomically. A line that isn't a JSON object (a write cut short by a crash) is skipped
/// when the file is read. When the queue holds more than `maxCount` signals or `maxBytes`
/// bytes, the oldest are dropped first. Only used from inside the ``Engine`` actor.
/// New signals are appended to the file; sending signals rewrites it atomically. A line that
/// isn't a JSON object (a write cut short by a crash) is skipped when the file is read. When
/// the queue holds more than `maxCount` signals or `maxBytes` bytes, the oldest are dropped
/// first. A full queue drops one signal for every new one, so it forgets them in memory at
/// once but only rewrites the file when `compactAfter` forgotten signals have piled up in
/// it (the next launch drops them again). Only used from inside the ``Engine`` actor.
struct DiskQueue {
let fileURL: URL
let maxCount: Int
let maxBytes: Int
let compactAfter: Int
private(set) var lines: [Data] = []
private var bytes = 0
/// Signals dropped from memory that are still in the file.
private var staleLines = 0
private var staleBytes = 0

init(directory: URL, maxCount: Int, maxBytes: Int = 5 * 1024 * 1024) {
init(directory: URL, maxCount: Int, maxBytes: Int = 5 * 1024 * 1024, compactAfter: Int? = nil) {
self.fileURL = directory.appendingPathComponent("signals.jsonl")
self.maxCount = max(1, maxCount)
self.maxBytes = max(Limits.maxBodyBytes, maxBytes)
self.compactAfter = max(1, compactAfter ?? max(50, self.maxCount / 10))
Self.prepare(directory)

guard let data = try? Data(contentsOf: fileURL) else { return }
let all = data.split(separator: UInt8(ascii: "\n"), omittingEmptySubsequences: true).map { Data($0) }
lines = all.filter(Self.isSignal)
bytes = lines.reduce(0) { $0 + $1.count }
let trimmed = trimToLimits()
let trimmed = trimToLimits().lines
if trimmed > 0 || lines.count != all.count || data.last != UInt8(ascii: "\n") {
rewrite()
}
Expand All @@ -38,12 +45,15 @@ struct DiskQueue {
mutating func append(_ line: Data) -> Int {
lines.append(line)
bytes += line.count
let dropped = trimToLimits()
let (dropped, droppedBytes) = trimToLimits()
appendToFile(line)
if dropped > 0 {
Log.debug("The queue is full; dropped the \(dropped) oldest signal(s).")
rewrite()
} else {
appendToFile(line)
staleLines += dropped
staleBytes += droppedBytes
if staleLines >= compactAfter || staleBytes >= maxBytes / 4 {
rewrite()
}
}
return dropped
}
Expand All @@ -60,20 +70,24 @@ struct DiskQueue {
mutating func removeAll() {
lines.removeAll()
bytes = 0
staleLines = 0
staleBytes = 0
try? FileManager.default.removeItem(at: fileURL)
}

// MARK: - Private

private mutating func trimToLimits() -> Int {
private mutating func trimToLimits() -> (lines: Int, bytes: Int) {
var dropped = 0
var droppedBytes = 0
// The newest signal always stays.
while lines.count - dropped > 1, lines.count - dropped > maxCount || bytes > maxBytes {
bytes -= lines[dropped].count
droppedBytes += lines[dropped].count
dropped += 1
}
if dropped > 0 { lines.removeFirst(dropped) }
return dropped
return (dropped, droppedBytes)
}

private func appendToFile(_ line: Data) {
Expand All @@ -93,7 +107,9 @@ struct DiskQueue {
}
}

private func rewrite() {
private mutating func rewrite() {
staleLines = 0
staleBytes = 0
guard !lines.isEmpty else {
try? FileManager.default.removeItem(at: fileURL)
return
Expand Down
28 changes: 21 additions & 7 deletions Sources/KestrelKit/Engine.swift
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ import Foundation
actor Engine {
/// A new session starts after this long in the background.
static let sessionTimeout: TimeInterval = 5 * 60
/// How long sending pauses after 401, 403 or 404, which a server fix or a new key can cure
/// without the app being relaunched.
static let unavailablePause: TimeInterval = 3600

private let uploader: Uploader
private let configuration: Kestrel.Configuration
Expand All @@ -20,8 +23,6 @@ actor Engine {
private var backgroundedAt: Date?
private var backoff = Backoff()
private var retryAt: Date?
/// Set after 401, 403 or 404; cleared by the next launch.
private var stoppedUntilRelaunch = false

init(uploader: Uploader, configuration: Kestrel.Configuration, environment: Environment) {
self.uploader = uploader
Expand Down Expand Up @@ -150,13 +151,19 @@ actor Engine {
private enum Stop {
case unavailable
case backoff(retryAfter: TimeInterval?)
/// The app opted out while a batch was on its way.
case disabled
}

private func flush() async {
guard isEnabled, !stoppedUntilRelaunch else { return }
// Before the check, so that an opt-out that comes after it can't be missed: it
// cancels sending, and nothing resets that again until the next flush.
uploader.control.reset()
guard isEnabled else { return }
if let retryAt, environment.now() < retryAt { return }

while true {
// Opting out can happen at any time, so each batch checks again.
while isEnabled {
let batch = nextBatch()
guard !batch.isEmpty else { return }
let (handled, stop) = await deliver(batch)
Expand All @@ -165,9 +172,12 @@ actor Engine {
case nil:
backoff.reset()
retryAt = nil
case .disabled:
return
case .unavailable:
stoppedUntilRelaunch = true
Log.debug("The server refused the key or has app analytics turned off; nothing more is sent until the next launch.")
let pause = Self.unavailablePause * min(max(environment.jitter(), 0), 1)
retryAt = environment.now().addingTimeInterval(pause)
Log.debug("The server refused the key or has app analytics turned off; trying again in \(Int(pause)) s.")
return
case let .backoff(retryAfter):
let delay = backoff.next(retryAfter: retryAfter, jitter: environment.jitter())
Expand Down Expand Up @@ -196,8 +206,12 @@ actor Engine {
/// Sends `lines`, splitting on 413. Returns how many of the first lines are done with
/// (accepted or dropped) and why it stopped early, if it did.
private func deliver(_ lines: ArraySlice<Data>) async -> (handled: Int, stop: Stop?) {
guard isEnabled else { return (0, .disabled) }
let body = Wire.body(lines: lines, sentAt: environment.now())
switch await uploader.send(body) {
let outcome = await uploader.send(body)
// An opt-out cancels the upload, which then looks like a failure: not one to back off for.
guard isEnabled else { return (0, .disabled) }
switch outcome {
case .accepted:
return (lines.count, nil)
case .rejected:
Expand Down
Loading
Loading