refactor handling of streams into observability

motivation: consistent handling of output streams changes: * define new API on observability to scope to report raw output and progress * stop passing outputstream around, instead use observability scope to emit output and progress events * implement output and progress handlers in the SwiftTool such that output organized sequentially and safely * update call sites

Author: tomerd

Sources/Basics/Observability.swift

@@ -27,7 +27,9 @@ public class ObservabilitySystem {
  description: "top scope",
  parent: .none,
  metadata: .none,
- diagnosticsHandler: handlerProvider.diagnosticsHandler
+ diagnosticsHandler: handlerProvider.diagnosticsHandler,
+ outputHandler: handlerProvider.outputHandler,
+ progressHandler: handlerProvider.progressHandler
  )
  }
 
@@ -36,8 +38,10 @@ public class ObservabilitySystem {
  self.init(SingleDiagnosticsHandler(handler))
  }
 
- private struct SingleDiagnosticsHandler: ObservabilityHandlerProvider, DiagnosticsHandler {
- var diagnosticsHandler: DiagnosticsHandler { self }
+ private struct SingleDiagnosticsHandler: ObservabilityHandlerProvider, ScopeDiagnosticsHandler, ScopeOutputHandler, ScopeProgressHandler {
+ var diagnosticsHandler: ScopeDiagnosticsHandler { self }
+ var outputHandler: ScopeOutputHandler { self }
+ var progressHandler: ScopeProgressHandler { self }
 
  let underlying: (ObservabilityScope, Diagnostic) -> Void
 
@@ -48,32 +52,49 @@ public class ObservabilitySystem {
  func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic) {
  self.underlying(scope, diagnostic)
  }
+
+ #warning("FIXME: should this do something?")
+ func handleOutput(scope: ObservabilityScope, output: String) {
+ // NOOP
+ }
+
+ func handleProgress(scope: ObservabilityScope, step: Int64, total: Int64, unit: String?, description: String?) {
+ // NOOP
+ }
  }
 }
 
 public protocol ObservabilityHandlerProvider {
- var diagnosticsHandler: DiagnosticsHandler { get }
+ var diagnosticsHandler: ScopeDiagnosticsHandler { get }
+ var progressHandler: ScopeProgressHandler { get }
+ var outputHandler: ScopeOutputHandler { get }
 }
 
 // MARK: - ObservabilityScope
 
-public final class ObservabilityScope: DiagnosticsEmitterProtocol, CustomStringConvertible {
+public final class ObservabilityScope: DiagnosticsEmitterProtocol, OutputEmitterProtocol, ProgressEmitterProtocol, CustomStringConvertible {
  public let description: String
  private let parent: ObservabilityScope?
  private let metadata: ObservabilityMetadata?
 
  private var diagnosticsHandler: DiagnosticsHanderWrapper
+ private var outputHandler: ScopeOutputHandler
+ private var progressHandler: ScopeProgressHandler
 
  fileprivate init(
  description: String,
  parent: ObservabilityScope?,
  metadata: ObservabilityMetadata?,
- diagnosticsHandler: DiagnosticsHandler
+ diagnosticsHandler: ScopeDiagnosticsHandler,
+ outputHandler: ScopeOutputHandler,
+ progressHandler: ScopeProgressHandler
  ) {
  self.description = description
  self.parent = parent
  self.metadata = metadata
  self.diagnosticsHandler = DiagnosticsHanderWrapper(diagnosticsHandler)
+ self.outputHandler = outputHandler
+ self.progressHandler = progressHandler
  }
 
  public func makeChildScope(description: String, metadata: ObservabilityMetadata? = .none) -> Self {
@@ -82,7 +103,9 @@ public final class ObservabilityScope: DiagnosticsEmitterProtocol, CustomStringC
  description: description,
  parent: self,
  metadata: mergedMetadata,
- diagnosticsHandler: self.diagnosticsHandler
+ diagnosticsHandler: self.diagnosticsHandler,
+ outputHandler: self.outputHandler,
+ progressHandler: self.progressHandler
  )
  }
 
@@ -123,11 +146,19 @@ public final class ObservabilityScope: DiagnosticsEmitterProtocol, CustomStringC
  self.diagnosticsHandler.handleDiagnostic(scope: self, diagnostic: diagnostic)
  }
 
- private struct DiagnosticsHanderWrapper: DiagnosticsHandler {
- private let underlying: DiagnosticsHandler
+ public func emit(output: String) {
+ self.outputHandler.handleOutput(scope: self, output: output)
+ }
+
+ public func emit(step: Int64, total: Int64, unit: String?, description: String?) {
+ self.progressHandler.handleProgress(scope: self, step: step, total: total, unit: unit, description: description)
+ }
+
+ private struct DiagnosticsHanderWrapper: ScopeDiagnosticsHandler {
+ private let underlying: ScopeDiagnosticsHandler
  private var _errorsReported = ThreadSafeBox<Bool>(false)
 
- init(_ underlying: DiagnosticsHandler) {
+ init(_ underlying: ScopeDiagnosticsHandler) {
  self.underlying = underlying
  }
 
@@ -146,7 +177,7 @@ public final class ObservabilityScope: DiagnosticsEmitterProtocol, CustomStringC
 
 // MARK: - Diagnostics
 
-public protocol DiagnosticsHandler {
+public protocol ScopeDiagnosticsHandler {
  func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic)
 }
 
@@ -567,14 +598,25 @@ extension ObservabilitySystem {
  self.init(DiagnosticsEngineAdapter(diagnosticEngine: diagnosticEngine))
  }
 
- private struct DiagnosticsEngineAdapter: ObservabilityHandlerProvider, DiagnosticsHandler {
+ private struct DiagnosticsEngineAdapter: ObservabilityHandlerProvider, ScopeDiagnosticsHandler, ScopeOutputHandler, ScopeProgressHandler {
  let diagnosticEngine: DiagnosticsEngine
 
- var diagnosticsHandler: DiagnosticsHandler { self }
+ var diagnosticsHandler: ScopeDiagnosticsHandler { self }
+ var outputHandler: ScopeOutputHandler { self }
+ var progressHandler: ScopeProgressHandler { self }
 
  func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic) {
  diagnosticEngine.emit(.init(diagnostic))
  }
+
+ #warning("FIXME: do something here?")
+ func handleOutput(scope: ObservabilityScope, output: String) {
+ // NOOP
+ }
+
+ func handleProgress(scope: ObservabilityScope, step: Int64, total: Int64, unit: String?, description: String?) {
+ // NOOP
+ }
  }
 }
 
@@ -663,3 +705,43 @@ extension ObservabilityMetadata {
  }
  }
 }
+
+// MARK: - Progress
+
+public protocol ScopeProgressHandler {
+ func handleProgress(scope: ObservabilityScope, step: Int64, total: Int64, unit: String?, description: String?)
+}
+
+public protocol ProgressEmitterProtocol {
+ func emit(step: Int64, total: Int64, unit: String?, description: String?)
+}
+
+extension ProgressEmitterProtocol {
+ public func emit(step: Int, total: Int, unit: String?, description: String?) {
+ self.emit(step: Int64(step), total: Int64(total), unit: unit, description: description)
+ }
+}
+
+// MARK: - User output
+
+public protocol ScopeOutputHandler {
+ func handleOutput(scope: ObservabilityScope, output: String)
+}
+
+public protocol OutputEmitterProtocol {
+ func emit(output: String)
+}
+
+extension OutputEmitterProtocol {
+ public func emit(output bytes: [UInt8]) {
+ if let output = String(bytes: bytes, encoding: .utf8) {
+ self.emit(output: output)
+ }
+ }
+
+ public func emit(output data: Data) {
+ if let output = String(data: data, encoding: .utf8) {
+ self.emit(output: output)
+ }
+ }
+}

Sources/Build/BuildOperation.swift

@@ -57,10 +57,10 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
  private let packageGraph = ThreadSafeBox<PackageGraph>()
 
  /// The output stream for the build delegate.
- private let outputStream: OutputByteStream
+ //private let outputStream: OutputByteStream
 
  /// The verbosity level to print out at
- private let logLevel: Basics.Diagnostic.Severity
+ //private let logLevel: Basics.Diagnostic.Severity
 
  /// File system to operate on
  private let fileSystem: TSCBasic.FileSystem
@@ -79,8 +79,8 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
  pluginScriptRunner: PluginScriptRunner,
  pluginWorkDirectory: AbsolutePath,
  disableSandboxForPluginCommands: Bool = false,
- outputStream: OutputByteStream,
- logLevel: Basics.Diagnostic.Severity,
+ //outputStream: OutputByteStream,
+ //logLevel: Basics.Diagnostic.Severity,
  fileSystem: TSCBasic.FileSystem,
  observabilityScope: ObservabilityScope
  ) {
@@ -90,8 +90,8 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
  self.pluginScriptRunner = pluginScriptRunner
  self.pluginWorkDirectory = pluginWorkDirectory
  self.disableSandboxForPluginCommands = disableSandboxForPluginCommands
- self.outputStream = outputStream
- self.logLevel = logLevel
+ //self.outputStream = outputStream
+ //self.logLevel = logLevel
  self.fileSystem = fileSystem
  self.observabilityScope = observabilityScope.makeChildScope(description: "Build Operation")
  }
@@ -353,10 +353,11 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
  // but it would require deeper changes in how we serialize BuildDescription
  // Output a dot graph
  if buildParameters.printManifestGraphviz {
+ #warning("FIXME: restore this (somewhere else)")
  // FIXME: this seems like the wrong place to print
- var serializer = DOTManifestSerializer(manifest: buildManifest)
- serializer.writeDOT(to: self.outputStream)
- self.outputStream.flush()
+ //var serializer = DOTManifestSerializer(manifest: buildManifest)
+ //serializer.writeDOT(to: self.outputStream)
+ //self.outputStream.flush()
  }
 
  // Finally create the llbuild manifest from the plan.
@@ -378,9 +379,9 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
  /// building the package structure target.
  private func createBuildSystem(buildDescription: BuildDescription?) throws -> SPMLLBuild.BuildSystem {
  // Figure out which progress bar we have to use during the build.
- let progressAnimation: ProgressAnimationProtocol = self.logLevel.isVerbose
- ? MultiLineNinjaProgressAnimation(stream: self.outputStream)
- : NinjaProgressAnimation(stream: self.outputStream)
+ //let progressAnimation: ProgressAnimationProtocol = self.logLevel.isVerbose
+ // ? MultiLineNinjaProgressAnimation(stream: self.outputStream)
+ //: NinjaProgressAnimation(stream: self.outputStream)
 
  let buildExecutionContext = BuildExecutionContext(
  buildParameters,
@@ -394,9 +395,9 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
  let buildSystemDelegate = BuildOperationBuildSystemDelegateHandler(
  buildSystem: self,
  buildExecutionContext: buildExecutionContext,
- outputStream: self.outputStream,
- progressAnimation: progressAnimation,
- logLevel: self.logLevel,
+ //outputStream: self.outputStream,
+ //progressAnimation: progressAnimation,
+ //logLevel: self.logLevel,
  observabilityScope: self.observabilityScope,
  delegate: self.delegate
  )
@@ -560,8 +561,9 @@ extension BuildSubset {
  }
 }
 
+/*
 extension Basics.Diagnostic.Severity {
  var isVerbose: Bool {
  return self <= .info
  }
-}
+}*/