Show progress bar while downloading Swift SDK bundles (#7315)

### Motivation:

The download operation takes a while, and it makes users feel like SwiftPM is stuck.

### Modifications:

This patch adds a progress indicator to the download operation to make it clear that SwiftPM is still working and how much work is left.

https://github.com/apple/swift-package-manager/assets/11702759/c535ede4-3d11-4992-9314-55a4e1e864d6

Author: kateinoigakukun

Sources/Basics/CMakeLists.txt

@@ -51,6 +51,7 @@ add_library(Basics
   Netrc.swift
   Observability.swift
   OSSignpost.swift
+  ProgressAnimation.swift
   SQLite.swift
   Sandbox.swift
   SendableTimeInterval.swift

Sources/Basics/ProgressAnimation.swift

@@ -0,0 +1,67 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import _Concurrency
+import protocol TSCUtility.ProgressAnimationProtocol
+
+/// A progress animation wrapper that throttles updates to a given interval.
+@_spi(SwiftPMInternal)
+public class ThrottledProgressAnimation: ProgressAnimationProtocol {
+    private let animation: ProgressAnimationProtocol
+    private let shouldUpdate: () -> Bool
+    private var pendingUpdate: (Int, Int, String)?
+
+    public convenience init(_ animation: ProgressAnimationProtocol, interval: ContinuousClock.Duration) {
+        self.init(animation, clock: ContinuousClock(), interval: interval)
+    }
+
+    public convenience init<C: Clock>(_ animation: ProgressAnimationProtocol, clock: C, interval: C.Duration) {
+        self.init(animation, now: { clock.now }, interval: interval, clock: C.self)
+    }
+
+    init<C: Clock>(
+      _ animation: ProgressAnimationProtocol,
+      now: @escaping () -> C.Instant, interval: C.Duration, clock: C.Type = C.self
+    ) {
+        self.animation = animation
+        var lastUpdate: C.Instant?
+        self.shouldUpdate = {
+            let now = now()
+            if let lastUpdate = lastUpdate, now < lastUpdate.advanced(by: interval) {
+                return false
+            }
+            // If we're over the interval or it's the first update, should update.
+            lastUpdate = now
+            return true
+        }
+    }
+
+    public func update(step: Int, total: Int, text: String) {
+        guard shouldUpdate() else {
+            pendingUpdate = (step, total, text)
+            return
+        }
+        pendingUpdate = nil
+        animation.update(step: step, total: total, text: text)
+    }
+
+    public func complete(success: Bool) {
+        if let (step, total, text) = pendingUpdate {
+            animation.update(step: step, total: total, text: text)
+        }
+        animation.complete(success: success)
+    }
+
+    public func clear() {
+        animation.clear()
+    }
+}

Sources/PackageModel/SwiftSDKs/SwiftSDKBundleStore.swift

@@ -15,6 +15,7 @@ import Basics
 import struct Foundation.URL
 import protocol TSCBasic.FileSystem
 import struct TSCBasic.RegEx
+import protocol TSCUtility.ProgressAnimationProtocol
 
 public final class SwiftSDKBundleStore {
     public enum Output: Equatable, CustomStringConvertible {
@@ -64,16 +65,21 @@ public final class SwiftSDKBundleStore {
     /// Closure invoked for output produced by this store during its operation.
     private let outputHandler: (Output) -> Void
 
+    /// Progress animation used for downloading SDK bundles.
+    private let downloadProgressAnimation: ProgressAnimationProtocol?
+
     public init(
         swiftSDKsDirectory: AbsolutePath,
         fileSystem: any FileSystem,
         observabilityScope: ObservabilityScope,
-        outputHandler: @escaping (Output) -> Void
+        outputHandler: @escaping (Output) -> Void,
+        downloadProgressAnimation: ProgressAnimationProtocol? = nil
     ) {
         self.swiftSDKsDirectory = swiftSDKsDirectory
         self.fileSystem = fileSystem
         self.observabilityScope = observabilityScope
         self.outputHandler = outputHandler
+        self.downloadProgressAnimation = downloadProgressAnimation
     }
 
     /// An array of valid Swift SDK bundles stored in ``SwiftSDKBundleStore//swiftSDKsDirectory``.
@@ -171,8 +177,20 @@ public final class SwiftSDKBundleStore {
                 _ = try await httpClient.execute(
                     request,
                     observabilityScope: self.observabilityScope,
-                    progress: nil
+                    progress: { step, total in
+                        guard let progressAnimation = self.downloadProgressAnimation else {
+                            return
+                        }
+                        let step = step > Int.max ? Int.max : Int(step)
+                        let total = total.map { $0 > Int.max ? Int.max : Int($0) } ?? step
+                        progressAnimation.update(
+                          step: step,
+                          total: total,
+                          text: "Downloading \(bundleURL.lastPathComponent)"
+                        )
+                    }
                 )
+                self.downloadProgressAnimation?.complete(success: true)
 
                 bundlePath = downloadedBundlePath
 

Sources/SwiftSDKTool/InstallSwiftSDK.swift

@@ -11,12 +11,14 @@
 //===----------------------------------------------------------------------===//
 
 import ArgumentParser
+@_spi(SwiftPMInternal)
 import Basics
 import CoreCommands
 import Foundation
 import PackageModel
 
 import var TSCBasic.stdoutStream
+import class TSCUtility.PercentProgressAnimation
 
 public struct InstallSwiftSDK: SwiftSDKSubcommand {
     public static let configuration = CommandConfiguration(
@@ -47,7 +49,10 @@ public struct InstallSwiftSDK: SwiftSDKSubcommand {
             swiftSDKsDirectory: swiftSDKsDirectory,
             fileSystem: self.fileSystem,
             observabilityScope: observabilityScope,
-            outputHandler: { print($0.description) }
+            outputHandler: { print($0.description) },
+            downloadProgressAnimation: ThrottledProgressAnimation(
+                PercentProgressAnimation(stream: stdoutStream, header: "Downloading"), interval: .milliseconds(300)
+            )
         )
         try await store.install(
             bundlePathOrURL: bundlePathOrURL,

Tests/BasicsTests/ProgressAnimationTests.swift

@@ -0,0 +1,76 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2014-2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import _Concurrency
+import XCTest
+import protocol TSCUtility.ProgressAnimationProtocol
+
+@_spi(SwiftPMInternal)
+@testable
+import Basics
+
+final class ProgressAnimationTests: XCTestCase {
+    class TrackingProgressAnimation: ProgressAnimationProtocol {
+        var steps: [Int] = []
+
+        func update(step: Int, total: Int, text: String) {
+            steps.append(step)
+        }
+
+        func complete(success: Bool) {}
+        func clear() {}
+    }
+
+    func testThrottledPercentProgressAnimation() {
+        do {
+            let tracking = TrackingProgressAnimation()
+            var now = ContinuousClock().now
+            let animation = ThrottledProgressAnimation(
+              tracking, now: { now }, interval: .milliseconds(100),
+              clock: ContinuousClock.self
+            )
+
+            // Update the animation 10 times with a 50ms interval.
+            let total = 10
+            for i in 0...total {
+                animation.update(step: i, total: total, text: "")
+                now += .milliseconds(50)
+            }
+            animation.complete(success: true)
+            XCTAssertEqual(tracking.steps, [0, 2, 4, 6, 8, 10])
+        }
+
+        do {
+            // Check that the last animation update is sent even if
+            // the interval has not passed.
+            let tracking = TrackingProgressAnimation()
+            var now = ContinuousClock().now
+            let animation = ThrottledProgressAnimation(
+              tracking, now: { now }, interval: .milliseconds(100),
+              clock: ContinuousClock.self
+            )
+
+            // Update the animation 10 times with a 50ms interval.
+            let total = 10
+            for i in 0...total-1 {
+                animation.update(step: i, total: total, text: "")
+                now += .milliseconds(50)
+            }
+            // The next update is at 1000ms, but we are at 950ms,
+            // so "step 9" is not sent yet.
+            XCTAssertEqual(tracking.steps, [0, 2, 4, 6, 8])
+            // After explicit "completion", the last step is flushed out.
+            animation.complete(success: true)
+            XCTAssertEqual(tracking.steps, [0, 2, 4, 6, 8, 9])
+        }
+    }
+}