Final API proposal - Baggage + Context (#34)

Author: ktoso

Package.resolved

@@ -2,7 +2,7 @@
 import PackageDescription
 
 let package = Package(
-    name: "swift-baggage-context",
+    name: "swift-context",
     products: [
         .library(
             name: "Baggage",
@@ -11,14 +11,14 @@ let package = Package(
             ]
         ),
         .library(
-            name: "BaggageLogging",
+            name: "BaggageContext",
             targets: [
-                "BaggageLogging",
+                "BaggageContext",
             ]
         ),
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-log.git", from: "1.3.0"),
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.4.0"),
     ],
     targets: [
         .target(
@@ -27,7 +27,7 @@ let package = Package(
         ),
 
         .target(
-            name: "BaggageLogging",
+            name: "BaggageContext",
             dependencies: [
                 "Baggage",
                 .product(name: "Logging", package: "swift-log"),
@@ -45,26 +45,25 @@ let package = Package(
         ),
 
         .testTarget(
-            name: "BaggageLoggingTests",
+            name: "BaggageContextTests",
             dependencies: [
                 "Baggage",
-                "BaggageLogging",
+                "BaggageContext",
             ]
         ),
 
         // ==== --------------------------------------------------------------------------------------------------------
         // MARK: Performance / Benchmarks
 
         .target(
-            name: "BaggageBenchmarks",
+            name: "BaggageContextBenchmarks",
             dependencies: [
-                "Baggage",
-                "BaggageLogging",
-                "BaggageBenchmarkTools",
+                "BaggageContext",
+                "BaggageContextBenchmarkTools",
             ]
         ),
         .target(
-            name: "BaggageBenchmarkTools",
+            name: "BaggageContextBenchmarkTools",
             dependencies: []
         ),
     ]

Package.swift

@@ -0,0 +1,218 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Baggage Context open source project
+//
+// Copyright (c) 2020 Moritz Lang and the Swift Baggage Context project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: Baggage
+
+/// A `Baggage` is a heterogeneous storage type with value semantics for keyed values in a type-safe fashion.
+///
+/// Its values are uniquely identified via `Baggage.Key`s (by type identity). These keys also dictate the type of
+/// value allowed for a specific key-value pair through their associated type `Value`.
+///
+/// ## Defining keys and accessing values
+/// Baggage keys are defined as types, most commonly case-less enums (as no actual instances are actually required)
+/// which conform to the `Baggage.Key` protocol:
+///
+///     private enum TestIDKey: Baggage.Key {
+///       typealias Value = String
+///     }
+///
+/// While defining a key, one should also immediately declare an extension on `Baggage`,
+/// to allow convenient and discoverable ways to interact with the baggage item, the extension should take the form of:
+///
+///     extension Baggage {
+///       var testID: String? {
+///         get {
+///           self[TestIDKey.self]
+///         } set {
+///           self[TestIDKey.self] = newValue
+///         }
+///       }
+///     }
+///
+/// For consistency, it is recommended to name key types with the `...Key` suffix (e.g. `SomethingKey`) and the property
+/// used to access a value identifier by such key the prefix of the key (e.g. `something`). Please also observe the usual
+/// Swift naming conventions, e.g. prefer `ID` to `Id` etc.
+///
+/// ## Usage
+/// Using a baggage container is fairly straight forward, as it boils down to using the prepared computed properties:
+///
+///     var baggage = Baggage.topLevel
+///     // set a new value
+///     baggage.testID = "abc"
+///     // retrieve a stored value
+///     let testID = baggage.testID ?? "default"
+///     // remove a stored value
+///     baggage.testIDKey = nil
+///
+/// Note that normally a baggage should not be "created" ad-hoc by user code, but rather it should be passed to it from
+/// a runtime. For example, when working in an HTTP server framework, it is most likely that the baggage is already passed
+/// directly or indirectly (e.g. in a `FrameworkContext`)
+///
+/// ### Accessing all values
+///
+/// The only way to access "all" values in a baggage context is by using the `forEach` function.
+/// The baggage container on purpose does not expose more functions to prevent abuse and treating it as too much of an
+/// arbitrary value smuggling container, but only make it convenient for tracing and instrumentation systems which need
+/// to access either specific or all items carried inside a baggage.
+public struct Baggage {
+    public typealias Key = BaggageKey
+
+    private var _storage = [AnyBaggageKey: Any]()
+
+    /// 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 "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,
+    /// message's or task's processing is initiated. For example, a framework handling requests, should create an empty
+    /// context when handling a request only to immediately populate it with useful trace information extracted from e.g.
+    /// request headers.
+    ///
+    /// ## Usage in applications
+    /// Application code should never have to create an empty context during the processing lifetime of any request,
+    /// and only should create contexts if some processing is performed in the background - thus the naming of this property.
+    ///
+    /// Usually, a framework such as an HTTP server or similar "request handler" would already provide users
+    /// with a context to be passed along through subsequent calls.
+    ///
+    /// If unsure where to obtain a context from, prefer using `.TODO("Not sure where I should get a context from here?")`,
+    /// 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 topLevel: Baggage {
+        return Baggage()
+    }
+}
+
+extension Baggage {
+    /// A baggage intended as a placeholder until a real value can be passed through a function call.
+    ///
+    /// It should ONLY be used while prototyping or when the passing of the proper context is not yet possible,
+    /// e.g. because an external library did not pass it correctly and has to be fixed before the proper context
+    /// can be obtained where the TO-DO is currently used.
+    ///
+    /// ## Crashing on TO-DO context creation
+    /// You may set the `BAGGAGE_CRASH_TODOS` variable while compiling a project in order to make calls to this function crash
+    /// with a fatal error, indicating where a to-do baggage context was used. This comes in handy when wanting to ensure that
+    /// a project never ends up using with code initially was written as "was lazy, did not pass context", yet the
+    /// project requires context passing to be done correctly throughout the application. Similar checks can be performed
+    /// at compile time easily using linters (not yet implemented), since it is always valid enough to detect a to-do context
+    /// being passed as illegal and warn or error when spotted.
+    ///
+    /// ## Example
+    ///
+    ///     let baggage = Baggage.TODO("The framework XYZ should be modified to pass us a context here, and we'd pass it along"))
+    ///
+    /// - Parameters:
+    ///   - 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.topLevel
+        #if BAGGAGE_CRASH_TODOS
+        fatalError("BAGGAGE_CRASH_TODOS: at \(file):\(line) (function \(function)), reason: \(reason)")
+        #else
+        context[TODOKey.self] = .init(file: file, line: line)
+        return context
+        #endif
+    }
+
+    private enum TODOKey: BaggageKey {
+        typealias Value = TODOLocation
+        static var nameOverride: String? {
+            return "todo"
+        }
+    }
+}
+
+extension Baggage {
+    /// Provides type-safe access to the baggage's values.
+    /// This API should ONLY be used inside of accessor implementations.
+    ///
+    /// End users rather than using this subscript should use "accessors" the key's author MUST define, following this pattern:
+    ///
+    ///     internal enum TestID: Baggage.Key {
+    ///         typealias Value = TestID
+    ///     }
+    ///
+    ///     extension Baggage {
+    ///       public internal(set) var testID: TestID? {
+    ///         get {
+    ///           self[TestIDKey.self]
+    ///         }
+    ///         set {
+    ///           self[TestIDKey.self] = newValue
+    ///         }
+    ///       }
+    ///     }
+    ///
+    /// This is in order to enforce a consistent style across projects and also allow for fine grained control over
+    /// who may set and who may get such property. Just access control to the Key type itself lacks such fidelity.
+    ///
+    /// Note that specific baggage and context types MAY (and usually do), offer also a way to set baggage values,
+    /// however in the most general case it is not required, as some frameworks may only be able to offer reading.
+    public subscript<Key: BaggageKey>(_ key: Key.Type) -> Key.Value? {
+        get {
+            guard let value = self._storage[AnyBaggageKey(key)] else { return nil }
+            // safe to force-cast as this subscript is the only way to set a value.
+            return (value as! Key.Value)
+        }
+        set {
+            self._storage[AnyBaggageKey(key)] = newValue
+        }
+    }
+
+    /// Number of contained baggage items.
+    public var count: Int {
+        return self._storage.count
+    }
+
+    /// Calls the given closure for each item contained in the underlying `Baggage`.
+    ///
+    /// Order of those invocations is NOT guaranteed and should not be relied on.
+    ///
+    /// - Parameter body: A closure invoked with the type erased key and value stored for the key in this baggage.
+    public func forEach(_ body: (AnyBaggageKey, Any) throws -> Void) rethrows {
+        try self._storage.forEach { key, value in
+            try body(key, value)
+        }
+    }
+}
+
+extension Baggage: CustomStringConvertible {
+    /// A context's description prints only keys of the contained values.
+    /// This is in order to prevent spilling a lot of detailed information of carried values accidentally.
+    ///
+    /// `Baggage`s are not intended to be printed "raw" but rather inter-operate with tracing, logging and other systems,
+    /// which can use the `forEach` function providing access to its underlying values.
+    public var description: String {
+        return "\(type(of: self).self)(keys: \(self._storage.map { $0.key.name }))"
+    }
+}
+
+/// Carried automatically by a "to do" baggage.
+/// It can be used to track where a context originated and which "to do" context must be fixed into a real one to avoid this.
+public struct TODOLocation {
+    /// Source file location where the to-do `Baggage` was created
+    public let file: String
+    /// Source line location where the to-do `Baggage` was created
+    public let line: UInt
+}