Skip to content
Open
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
38 changes: 33 additions & 5 deletions Sources/RecorderCore/HTTP/Routes.swift
Original file line number Diff line number Diff line change
Expand Up @@ -63,18 +63,18 @@ public enum RecorderRoutes {
let authed = api.group().add(middleware: BearerAuthMiddleware(services: services))
authed.get("recordings") { _, _ in
let records = await services.store.recordings()
return try JSONResponse.make(records.map { publicRecording($0, services: services) })
return try await JSONResponse.make(publicRecordings(records, services: services))
}
authed.post("recordings") { request, context in
let body = try await request.decode(as: CreateRecordingRequest.self, context: context)
let key = request.headers[idempotencyHeader]
let (record, created) = try await services.scheduler.create(body, deviceID: context.device?.id, idempotencyKey: key)
return try JSONResponse.make(publicRecording(record, services: services), status: created ? .created : .ok)
return try await JSONResponse.make(publicRecording(record, services: services), status: created ? .created : .ok)
}
authed.post("recordings/:id/stop") { _, context in
let id = try recordingID(context)
let record = try await services.scheduler.stop(id)
return try JSONResponse.make(publicRecording(record, services: services))
return try await JSONResponse.make(publicRecording(record, services: services))
}
authed.delete("recordings/:id") { _, context in
try await services.scheduler.delete(recordingID(context))
Expand Down Expand Up @@ -213,12 +213,40 @@ public enum RecorderRoutes {
return id
}

/// Live recordings report stats read from disk; finished ones use the cache.
static func publicRecording(_ record: RecordingRecord, services: RecorderServices) -> Recording {
/// Live recordings report stats read from disk via the coalescing live stats coordinator;
/// finished ones use the cached statistics in the store.
static func publicRecording(_ record: RecordingRecord, services: RecorderServices) async -> Recording {
guard record.status == .recording else { return record.publicRecording() }
let stats = await services.liveStats.stats(for: record.id, in: services.store.mediaDirectory(for: record.id))
return record.publicRecording(media: stats)
}

/// Synchronous fallback when direct inspection is needed without coordination.
static func publicRecordingSync(_ record: RecordingRecord, services: RecorderServices) -> Recording {
guard record.status == .recording else { return record.publicRecording() }
return record.publicRecording(media: MediaInspector.stats(in: services.store.mediaDirectory(for: record.id)))
}

/// Resolves all records into public DTOs, coalescing live media stats queries concurrently.
static func publicRecordings(_ records: [RecordingRecord], services: RecorderServices) async -> [Recording] {
guard records.contains(where: { $0.status == .recording }) else {
return records.map { $0.publicRecording() }
}
return await withTaskGroup(of: (Int, Recording).self) { group in
for (index, record) in records.enumerated() {
group.addTask {
let pub = await publicRecording(record, services: services)
return (index, pub)
}
}
var output = [Recording?](repeating: nil, count: records.count)
for await (index, pub) in group {
output[index] = pub
}
return output.compactMap { $0 }
}
}

/// `scheme://host[:port]` the client used, so the link is reachable from
/// where the request came from. Falls back to `PUBLIC_URL`, then localhost.
static func baseURL(for request: Request, config: RecorderConfig) -> String {
Expand Down
9 changes: 8 additions & 1 deletion Sources/RecorderCore/RecorderConfig.swift
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ public struct RecorderConfig: Sendable {
public var singleFileRecordings: Bool
/// Lifetime of playback grants.
public var playbackGrantLifetime: TimeInterval = 12 * 3600
/// `LIVE_STATS_FRESHNESS` — maximum age of cached stats for active recordings in seconds.
public var liveStatsFreshness: TimeInterval = 2.0

public init(
host: String = "0.0.0.0",
Expand All @@ -49,7 +51,8 @@ public struct RecorderConfig: Sendable {
ffmpegPath: String = "ffmpeg",
logLevel: Logger.Level = .info,
bonjourEnabled: Bool = true,
singleFileRecordings: Bool = false
singleFileRecordings: Bool = false,
liveStatsFreshness: TimeInterval = 2.0
) {
self.host = host
self.port = port
Expand All @@ -62,6 +65,7 @@ public struct RecorderConfig: Sendable {
self.logLevel = logLevel
self.bonjourEnabled = bonjourEnabled
self.singleFileRecordings = singleFileRecordings
self.liveStatsFreshness = liveStatsFreshness
}

/// Builds a config from environment variables, falling back to defaults.
Expand All @@ -84,6 +88,9 @@ public struct RecorderConfig: Sendable {
if let single = value("SINGLE_FILE_RECORDINGS") {
config.singleFileRecordings = ["1", "true", "yes", "on"].contains(single.lowercased())
}
if let liveFreshness = value("LIVE_STATS_FRESHNESS").flatMap(Double.init) {
config.liveStatsFreshness = liveFreshness
}
return config
}

Expand Down
17 changes: 16 additions & 1 deletion Sources/RecorderCore/RecorderServices.swift
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,15 @@ public struct RecorderServices: Sendable {
public let scheduler: RecordingScheduler
public let pairing: PairingManager
public let signer: PlaybackSigner
public let liveStats: LiveStatsCoordinator
public let now: NowProvider
public let logger: Logger

public init(
config: RecorderConfig,
launcher: any RecordingProcessLauncher,
disk: any DiskSpaceProviding = FileSystemDiskSpace(),
liveStats: LiveStatsCoordinator? = nil,
now: @escaping NowProvider = { Date() },
logger: Logger = Logger(label: "lume-recorder"),
configureScheduler: (inout RecordingScheduler.Options) -> Void = { _ in }
Expand All @@ -29,10 +31,23 @@ public struct RecorderServices: Sendable {
throw RecorderError.invalidRequest("server.json holds an invalid playback secret")
}
self.signer = signer
let statsCoordinator = liveStats ?? LiveStatsCoordinator(
freshness: config.liveStatsFreshness,
now: now
)
self.liveStats = statsCoordinator
var options = RecordingScheduler.Options(maxConcurrent: config.maxConcurrent, minFreeBytes: config.minFreeBytes)
options.singleFileRecordings = config.singleFileRecordings
configureScheduler(&options)
scheduler = RecordingScheduler(store: store, launcher: launcher, options: options, disk: disk, now: now, logger: logger)
scheduler = RecordingScheduler(
store: store,
launcher: launcher,
options: options,
disk: disk,
liveStats: statsCoordinator,
now: now,
logger: logger
)
pairing = PairingManager(directory: config.dataDirectory, now: now, logger: logger)
}

Expand Down
161 changes: 161 additions & 0 deletions Sources/RecorderCore/Recording/LiveStatsCoordinator.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
import Foundation

/// Duration and size of a recording's media on disk.
/// Coordinates disk inspection of active recordings to:
/// 1. Coalesce concurrent requests into a single-flight scan.
/// 2. Cache stats for an explicit short freshness bound (avoiding repetitive full directory scans).
/// 3. Offload blocking disk I/O onto a dedicated executor so Hummingbird and cooperative threads remain responsive.
/// 4. Invalidate / update on append, retry, stop, delete, and finalization.
public actor LiveStatsCoordinator {
public typealias Inspector = @Sendable (URL) -> MediaStats

public struct Options: Sendable {
public var freshness: TimeInterval

public init(freshness: TimeInterval = 2.0) {
self.freshness = freshness
}
}

private struct Entry: Sendable {
var stats: MediaStats
var recordedAt: Date
}

private struct InFlightScan {
let scanID: UUID
let task: Task<MediaStats, Never>
}

private var cache: [UUID: Entry] = [:]
private var inFlight: [UUID: InFlightScan] = [:]
private var generations: [UUID: Int] = [:]

public let freshness: TimeInterval
private let now: NowProvider
private let ioQueue: DispatchQueue
private let inspector: Inspector

public private(set) var totalScans: Int = 0
public private(set) var scansByID: [UUID: Int] = [:]

public init(
freshness: TimeInterval = 2.0,
now: @escaping NowProvider = { Date() },
ioQueue: DispatchQueue = DispatchQueue(
label: "com.lume.recorder.live-stats-io",
qos: .utility,
attributes: .concurrent
),
inspector: @escaping Inspector = { MediaInspector.stats(in: $0) }
) {
self.freshness = freshness
self.now = now
self.ioQueue = ioQueue
self.inspector = inspector
}

/// Returns stats for the active recording in `directory`.
/// Concurrent callers for the same `id` share an in-flight scan.
/// Subsequent callers within `freshness` receive the cached stats.
public func stats(for id: UUID, in directory: URL) async -> MediaStats {
let currentTime = now()

// 1. Fresh cache hit
if let entry = cache[id], currentTime.timeIntervalSince(entry.recordedAt) < freshness {
return entry.stats
}

// 2. Coalesce onto in-flight scan
if let existing = inFlight[id] {
return await existing.task.value
}

// 3. Initiate single-flight scan on dedicated I/O executor
let gen = generations[id, default: 0]
let scanID = UUID()
totalScans += 1
scansByID[id, default: 0] += 1

let queue = ioQueue
let inspect = inspector
let task = Task<MediaStats, Never> {
await withCheckedContinuation { continuation in
queue.async {
let s = inspect(directory)
continuation.resume(returning: s)
}
}
}

inFlight[id] = InFlightScan(scanID: scanID, task: task)
let result = await task.value

// Clean up in-flight pointer if it wasn't superseded
if inFlight[id]?.scanID == scanID {
inFlight.removeValue(forKey: id)
}

// Only cache if this recording wasn't invalidated during the scan
if generations[id, default: 0] == gen {
cache[id] = Entry(stats: result, recordedAt: now())
}

return result
}

/// Read cached stats without triggering an inspection.
public func cachedStats(for id: UUID) -> MediaStats? {
guard let entry = cache[id], now().timeIntervalSince(entry.recordedAt) < freshness else {
return nil
}
return entry.stats
}

/// Directly updates cached stats (e.g. from an authoritative inspection).
public func update(_ id: UUID, stats: MediaStats) {
generations[id, default: 0] += 1
cache[id] = Entry(stats: stats, recordedAt: now())
}

/// Invalidates cached stats and cancels any in-flight scan for `id`.
/// Called on retry, stop, delete, and finalization.
public func invalidate(_ id: UUID) {
generations[id, default: 0] += 1
cache.removeValue(forKey: id)
if let scan = inFlight.removeValue(forKey: id) {
scan.task.cancel()
}
}

/// Notifies that media was appended; invalidates cache so the next poll refreshes.
public func didAppendSegment(for id: UUID) {
invalidate(id)
}

/// Returns the number of disk scans executed for `id`.
public func scanCount(for id: UUID) -> Int {
scansByID[id] ?? 0
}

/// Returns the total number of scans executed across all recordings.
public func totalScanCount() -> Int {
totalScans
}

/// Resets all scan counters (for testing).
public func resetScanCounts() {
totalScans = 0
scansByID.removeAll()
}

/// Discards all cached entries and in-flight scans.
public func reset() {
cache.removeAll()
for (_, scan) in inFlight {
scan.task.cancel()
}
inFlight.removeAll()
generations.removeAll()
}
}
16 changes: 16 additions & 0 deletions Sources/RecorderCore/Recording/RecordingScheduler.swift
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ public actor RecordingScheduler: Service {
}

public nonisolated let options: Options
public let liveStats: LiveStatsCoordinator?
private let store: RecorderStore
private let launcher: any RecordingProcessLauncher
private let disk: any DiskSpaceProviding
Expand All @@ -101,13 +102,15 @@ public actor RecordingScheduler: Service {
launcher: any RecordingProcessLauncher,
options: Options,
disk: any DiskSpaceProviding = FileSystemDiskSpace(),
liveStats: LiveStatsCoordinator? = nil,
now: @escaping NowProvider = { Date() },
logger: Logger = Logger(label: "lume-recorder.scheduler")
) {
self.store = store
self.launcher = launcher
self.options = options
self.disk = disk
self.liveStats = liveStats
self.now = now
self.logger = logger
}
Expand Down Expand Up @@ -243,6 +246,7 @@ public actor RecordingScheduler: Service {
job.task?.cancel()
}
await job.task?.value
await liveStats?.invalidate(id)
logger.info("Recording \(id) stopped on request")
return await store.recording(id) ?? record
}
Expand All @@ -262,6 +266,7 @@ public actor RecordingScheduler: Service {
await job.task?.value
jobs[id] = nil
}
await liveStats?.invalidate(id)
try? FileManager.default.removeItem(at: store.mediaDirectory(for: id))
try await store.removeRecording(id)
if let key = record.idempotencyKey, let device = record.createdByDeviceID {
Expand Down Expand Up @@ -289,6 +294,12 @@ public actor RecordingScheduler: Service {
await job.task?.value
}
jobs.removeAll()
await liveStats?.reset()
}

/// Invalidate cached live statistics for a recording (e.g. after appending media).
public func invalidateLiveStats(_ id: UUID) async {
await liveStats?.invalidate(id)
}

// MARK: Queries
Expand Down Expand Up @@ -369,6 +380,9 @@ public actor RecordingScheduler: Service {

let attempt = record.attempts + 1
_ = try? await store.update(id) { $0.attempts = attempt }
if attempt > 1 {
await liveStats?.invalidate(id)
}
try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
let spec = RecordingAttemptSpec(
recordingID: id,
Expand Down Expand Up @@ -442,6 +456,7 @@ public actor RecordingScheduler: Service {
}
let delay = min(backoff, timeLeft)
logger.warning("Recording \(id) source ended early; retrying in \(Int(delay.rounded())) s")
await liveStats?.invalidate(id)
do {
try await Task.sleep(for: .seconds(delay))
} catch {
Expand Down Expand Up @@ -478,6 +493,7 @@ public actor RecordingScheduler: Service {
}
let stats = MediaInspector.stats(in: directory)
let current = now()
await liveStats?.invalidate(id)
if stats.segmentCount > 0 {
_ = try? await store.update(id) {
$0.status = .completed
Expand Down
2 changes: 2 additions & 0 deletions Sources/lume-recorder/LumeRecorderCommand.swift
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ struct Serve: AsyncParsableCommand {
name: .customLong("single-file-recordings"),
help: "Merge each finished recording into one recording.ts (env SINGLE_FILE_RECORDINGS=1)."
) var singleFileRecordings = false
@Option(name: .customLong("live-stats-freshness"), help: "Live stats cache freshness in seconds (env LIVE_STATS_FRESHNESS, default 2.0).") var liveStatsFreshness: Double?

func run() async throws {
var config = RecorderConfig.fromEnvironment()
Expand All @@ -51,6 +52,7 @@ struct Serve: AsyncParsableCommand {
}
if noBonjour { config.bonjourEnabled = false }
if singleFileRecordings { config.singleFileRecordings = true }
if let liveStatsFreshness { config.liveStatsFreshness = liveStatsFreshness }
guard config.maxConcurrent >= 1 else { throw ValidationError("max-concurrent must be at least 1") }

let level = config.logLevel
Expand Down
Loading