review feedback: background -> topLevel rename, as it makes more sense

yet keeps the "huh?" effect of "this likely is wrong" if it appears in
the middle of a codebase

Author: ktoso

Diff for: Sources/Baggage/Baggage.swift

@@ -47,7 +47,7 @@
 /// ## Usage
 /// Using a baggage container is fairly straight forward, as it boils down to using the prepared computed properties:
 ///
-///     var context = Baggage.background
+///     var context = Baggage.topLevel
 ///     // set a new value
 ///     context.testID = "abc"
 ///     // retrieve a stored value
@@ -70,17 +70,16 @@ public struct Baggage {
 
     private var _storage = [AnyBaggageKey: Any]()
 
-    /// Internal on purpose, please use `Baggage.TODO` or `Baggage.background` to create an "empty" context,
+    /// Internal on purpose, please use `Baggage.TODO` or `Baggage.topLevel` to create an "empty" context,
     /// which carries more meaning to other developers why an empty context was used.
     init() {}
 }
 
 extension Baggage {
-    /// Creates a new empty baggage, generally used for background processing tasks or an "initial" baggage to be immediately
-    /// populated with some values by a framework or runtime.
-    ///
-    /// Typically, this would only be called in a "top" or "background" setting, such as the main function, initialization,
-    /// tests, beginning of some background task or some other top-level baggage to be immediately populated with incoming request/message information.
+    /// Creates a new empty "top level" baggage, generally used as an "initial" baggage to immediately be populated with
+    /// some values by a framework or runtime. Another use case is for tasks starting in the "background" (e.g. on a timer),
+    /// which don't have a "request context" per se that they can pick up, and as such they have to create a "top level"
+    /// baggage for their work.
     ///
     /// ## Usage in frameworks and libraries
     /// This function is really only intended to be used frameworks and libraries, at the "top-level" where a request's,
@@ -99,7 +98,7 @@ extension Baggage {
     /// in order to inform other developers that the lack of context passing was not done on purpose, but rather because either
     /// not being sure where to obtain a context from, or other framework limitations -- e.g. the outer framework not being
     /// baggage context aware just yet.
-    public static var background: Baggage {
+    public static var topLevel: Baggage {
         return Baggage()
     }
 }
@@ -127,7 +126,7 @@ extension Baggage {
     ///   - reason: Informational reason for developers, why a placeholder context was used instead of a proper one,
     /// - Returns: Empty "to-do" baggage context which should be eventually replaced with a carried through one, or `background`.
     public static func TODO(_ reason: StaticString? = "", function: String = #function, file: String = #file, line: UInt = #line) -> Baggage {
-        var context = Baggage.background
+        var context = Baggage.topLevel
         #if BAGGAGE_CRASH_TODOS
         fatalError("BAGGAGE_CRASH_TODOS: at \(file):\(line) (function \(function)), reason: \(reason)")
         #else

Diff for: Sources/BaggageContext/Context.swift

@@ -100,20 +100,20 @@ public struct DefaultContext: Context {
         didSet {
             // Since someone could have completely replaced the logger (not just changed the log level),
             // we have to update the baggage again, since perhaps the new logger has empty metadata.
-            self.logger.update(previous: .background, latest: self.baggage)
+            self.logger.update(previous: .topLevel, latest: self.baggage)
         }
     }
 
     public init(baggage: Baggage, logger: Logger) {
         self.baggage = baggage
         self.logger = logger
-        self.logger.update(previous: .background, latest: baggage)
+        self.logger.update(previous: .topLevel, latest: baggage)
     }
 
     public init<C>(context: C) where C: Context {
         self.baggage = context.baggage
         self.logger = context.logger
-        self.logger.update(previous: .background, latest: self.baggage)
+        self.logger.update(previous: .topLevel, latest: self.baggage)
     }
 }
 
@@ -172,9 +172,11 @@ extension DefaultContext {
 // MARK: Context Initializers
 
 extension DefaultContext {
-    /// An empty baggage context intended as the "root" or "initial" baggage context background processing tasks, or as the "root" baggage context.
+    /// Creates a new empty "top level" default baggage context, generally used as an "initial" context to immediately be populated with
+    /// some values by a framework or runtime. Another use case is for tasks starting in the "background" (e.g. on a timer),
+    /// which don't have a "request context" per se that they can pick up, and as such they have to create a "top level"
+    /// baggage for their work.
     ///
-    /// It is never canceled, has no values, and has no deadline.
     /// It is typically used by the main function, initialization, and tests, and as the top-level Context for incoming requests.
     ///
     /// ### Usage in frameworks and libraries
@@ -194,8 +196,8 @@ extension DefaultContext {
     /// such that other developers are informed that the lack of context was not done on purpose, but rather because either
     /// not being sure where to obtain a context from, or other framework limitations -- e.g. the outer framework not being
     /// context aware just yet.
-    public static func background(logger: Logger) -> DefaultContext {
-        return .init(baggage: .background, logger: logger)
+    public static func topLevel(logger: Logger) -> DefaultContext {
+        return .init(baggage: .topLevel, logger: logger)
     }
 }
 

Diff for: Sources/BaggageContextBenchmarks/BaggageLoggingBenchmarks.swift

@@ -62,7 +62,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
         name: pad("BaggageLoggingBenchmarks.0_log_noop_loggerWithBaggage_small"),
         runFunction: { iters in
             let logger = Logger(label: "0_log_noop_loggerWithBaggage_small", factory: { _ in SwiftLogNoOpLogHandler() })
-            var baggage = Baggage.background
+            var baggage = Baggage.topLevel
             baggage[TestK1.self] = "k1-value"
             baggage[TestK2.self] = "k2-value"
             baggage[TestK3.self] = "k3-value"
@@ -77,7 +77,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: pad("BaggageLoggingBenchmarks.0_log_noop_context_with_baggage_small"),
         runFunction: { iters in
-            var context = DefaultContext.background(logger: Logger(label: "0_log_noop_context_with_baggage_small", factory: { _ in SwiftLogNoOpLogHandler() }))
+            var context = DefaultContext.topLevel(logger: Logger(label: "0_log_noop_context_with_baggage_small", factory: { _ in SwiftLogNoOpLogHandler() }))
             context.baggage[TestK1.self] = "k1-value"
             context.baggage[TestK2.self] = "k2-value"
             context.baggage[TestK3.self] = "k3-value"
@@ -125,7 +125,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
         name: pad("BaggageLoggingBenchmarks.1_log_real_loggerWithBaggage_small"),
         runFunction: { iters in
             let logger = Logger(label: "1_log_real_loggerWithBaggage_small", factory: StreamLogHandler.standardError)
-            var baggage = Baggage.background
+            var baggage = Baggage.topLevel
             baggage[TestK1.self] = "k1-value"
             baggage[TestK2.self] = "k2-value"
             baggage[TestK3.self] = "k3-value"
@@ -140,7 +140,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: pad("BaggageLoggingBenchmarks.1_log_real_context_with_baggage_small"),
         runFunction: { iters in
-            var context = DefaultContext.background(logger: Logger(label: "1_log_real_context_with_baggage_small", factory: StreamLogHandler.standardError))
+            var context = DefaultContext.topLevel(logger: Logger(label: "1_log_real_context_with_baggage_small", factory: StreamLogHandler.standardError))
             context.baggage[TestK1.self] = "k1-value"
             context.baggage[TestK2.self] = "k2-value"
             context.baggage[TestK3.self] = "k3-value"
@@ -188,7 +188,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
         name: pad("BaggageLoggingBenchmarks.2_log_real-trace_loggerWithBaggage_small"),
         runFunction: { iters in
             let logger = Logger(label: "2_log_real-trace_loggerWithBaggage_small", factory: StreamLogHandler.standardError)
-            var baggage = Baggage.background
+            var baggage = Baggage.topLevel
             baggage[TestK1.self] = "k1-value"
             baggage[TestK2.self] = "k2-value"
             baggage[TestK3.self] = "k3-value"
@@ -203,7 +203,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: pad("BaggageLoggingBenchmarks.2_log_real-trace_context_with_baggage_small"),
         runFunction: { iters in
-            var context = DefaultContext.background(logger: Logger(label: "2_log_real-trace_context_with_baggage_small", factory: StreamLogHandler.standardError))
+            var context = DefaultContext.topLevel(logger: Logger(label: "2_log_real-trace_context_with_baggage_small", factory: StreamLogHandler.standardError))
             context.baggage[TestK1.self] = "k1-value"
             context.baggage[TestK2.self] = "k2-value"
             context.baggage[TestK3.self] = "k3-value"
@@ -222,7 +222,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: pad("BaggageLoggingBenchmarks.3_log_real_small_context_materializeOnce"),
         runFunction: { iters in
-            var context = DefaultContext.background(logger: Logger(label: "3_log_real_context_materializeOnce", factory: StreamLogHandler.standardError))
+            var context = DefaultContext.topLevel(logger: Logger(label: "3_log_real_context_materializeOnce", factory: StreamLogHandler.standardError))
             context.baggage[TestK1.self] = "k1-value"
             context.baggage[TestK2.self] = "k2-value"
             context.baggage[TestK3.self] = "k3-value"
@@ -237,7 +237,7 @@ public let BaggageLoggingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: pad("BaggageLoggingBenchmarks.3_log_real-trace_small_context_materializeOnce"),
         runFunction: { iters in
-            var context = DefaultContext.background(logger: Logger(label: "3_log_real_context_materializeOnce", factory: StreamLogHandler.standardError))
+            var context = DefaultContext.topLevel(logger: Logger(label: "3_log_real_context_materializeOnce", factory: StreamLogHandler.standardError))
             context.baggage[TestK1.self] = "k1-value"
             context.baggage[TestK2.self] = "k2-value"
             context.baggage[TestK3.self] = "k3-value"

Diff for: Sources/BaggageContextBenchmarks/BaggagePassingBenchmarks.swift

@@ -22,7 +22,7 @@ public let BaggagePassingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: "BaggagePassingBenchmarks.pass_async_empty_100_000         ",
         runFunction: { _ in
-            let context = Baggage.background
+            let context = Baggage.topLevel
             pass_async(context: context, times: 100_000)
         },
         tags: [],
@@ -32,7 +32,7 @@ public let BaggagePassingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: "BaggagePassingBenchmarks.pass_async_smol_100_000          ",
         runFunction: { _ in
-            var context = Baggage.background
+            var context = Baggage.topLevel
             context.k1 = "one"
             context.k2 = "two"
             context.k3 = "three"
@@ -46,7 +46,7 @@ public let BaggagePassingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: "BaggagePassingBenchmarks.pass_async_small_nonconst_100_000",
         runFunction: { _ in
-            var context = Baggage.background
+            var context = Baggage.topLevel
             context.k1 = "\(Int.random(in: 1 ... Int.max))"
             context.k2 = "\(Int.random(in: 1 ... Int.max))"
             context.k3 = "\(Int.random(in: 1 ... Int.max))"
@@ -66,7 +66,7 @@ public let BaggagePassingBenchmarks: [BenchmarkInfo] = [
     BenchmarkInfo(
         name: "BaggagePassingBenchmarks.pass_mut_async_small_100_000     ",
         runFunction: { _ in
-            var context = Baggage.background
+            var context = Baggage.topLevel
             context.k1 = "\(Int.random(in: 1 ... Int.max))"
             context.k2 = "\(Int.random(in: 1 ... Int.max))"
             context.k3 = "\(Int.random(in: 1 ... Int.max))"

Diff for: Tests/BaggageContextTests/BaggageContextTests.swift

@@ -18,7 +18,7 @@ import XCTest
 
 final class BaggageContextTests: XCTestCase {
     func test_ExampleFrameworkContext_dumpBaggage() throws {
-        var baggage = Baggage.background
+        var baggage = Baggage.topLevel
         let logger = Logger(label: "TheLogger")
 
         baggage.testID = 42
@@ -43,7 +43,7 @@ final class BaggageContextTests: XCTestCase {
     }
 
     func test_ExampleMutableFrameworkContext_log_withBaggage() throws {
-        let baggage = Baggage.background
+        let baggage = Baggage.topLevel
         let logging = TestLogging()
         let logger = Logger(label: "TheLogger", factory: { label in logging.make(label: label) })
 
@@ -66,7 +66,7 @@ final class BaggageContextTests: XCTestCase {
     }
 
     func test_ExampleMutableFrameworkContext_log_prefersBaggageContextOverExistingLoggerMetadata() {
-        let baggage = Baggage.background
+        let baggage = Baggage.topLevel
         let logging = TestLogging()
         var logger = Logger(label: "TheLogger", factory: { label in logging.make(label: label) })
         logger[metadataKey: "secondIDExplicitlyNamed"] = "set on logger"
@@ -126,7 +126,7 @@ struct CoolFrameworkContext: BaggageContext.Context {
         return self._logger.with(self.baggage)
     }
 
-    var baggage: Baggage = .background
+    var baggage: Baggage = .topLevel
 
     // framework context defines other values as well
     let frameworkField: String = ""

Diff for: Tests/BaggageContextTests/FrameworkContextTests.swift

@@ -44,7 +44,7 @@ final class FrameworkBaggageContextTests: XCTestCase {
 }
 
 private struct TestFrameworkContext: Context {
-    var baggage = Baggage.background
+    var baggage = Baggage.topLevel
 
     private var _logger = Logger(label: "test")
     var logger: Logger {

Diff for: Tests/BaggageTests/BaggageTests.swift

@@ -18,7 +18,7 @@ final class BaggageTests: XCTestCase {
     func testSubscriptAccess() {
         let testID = 42
 
-        var baggage = Baggage.background
+        var baggage = Baggage.topLevel
         XCTAssertNil(baggage[TestIDKey.self])
 
         baggage[TestIDKey.self] = testID
@@ -31,7 +31,7 @@ final class BaggageTests: XCTestCase {
     func testRecommendedConvenienceExtension() {
         let testID = 42
 
-        var baggage = Baggage.background
+        var baggage = Baggage.topLevel
         XCTAssertNil(baggage.testID)
 
         baggage.testID = testID
@@ -42,18 +42,18 @@ final class BaggageTests: XCTestCase {
     }
 
     func testEmptyBaggageDescription() {
-        XCTAssertEqual(String(describing: Baggage.background), "Baggage(keys: [])")
+        XCTAssertEqual(String(describing: Baggage.topLevel), "Baggage(keys: [])")
     }
 
     func testSingleKeyBaggageDescription() {
-        var baggage = Baggage.background
+        var baggage = Baggage.topLevel
         baggage.testID = 42
 
         XCTAssertEqual(String(describing: baggage), #"Baggage(keys: ["TestIDKey"])"#)
     }
 
     func testMultiKeysBaggageDescription() {
-        var baggage = Baggage.background
+        var baggage = Baggage.topLevel
         baggage.testID = 42
         baggage[SecondTestIDKey.self] = "test"
 
@@ -80,15 +80,15 @@ final class BaggageTests: XCTestCase {
     }
 
     func test_todo_empty() {
-        let context = Baggage.background
+        let context = Baggage.topLevel
         _ = context // avoid "not used" warning
 
         // TODO: Can't work with protocols; re-consider the entire carrier approach... Context being a Baggage + Logger, and a specific type.
         // static member 'empty' cannot be used on protocol metatype 'BaggageContextProtocol.Protocol'
 //        func take(context: BaggageContextProtocol) {
 //            _ = context // ignore
 //        }
-//        take(context: .background)
+//        take(context: .topLevel)
     }
 }