mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
### Motivation: `Logger.MetadataValue.attributes` documents the setter as a no-op for `.dictionary` and `.array`, but it calls `assertionFailure` there. Debug builds trap, release builds do the documented no-op. ### Modifications: Doc comment only. The assertion stays; the comment now says setting attributes on a collection value is a programmer error, that debug builds assert and release builds leave the value unchanged, and to set attributes on the leaf values instead. ### Result: The documentation matches the code. No behaviour change. Found by an automated audit loop (Claude); patch and description reviewed by me.
556 lines
20 KiB
Swift
556 lines
20 KiB
Swift
//===----------------------------------------------------------------------===//
|
||
//
|
||
// This source file is part of the Swift Logging API open source project
|
||
//
|
||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||
// Licensed under Apache License v2.0
|
||
//
|
||
// See LICENSE.txt for license information
|
||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||
//
|
||
// SPDX-License-Identifier: Apache-2.0
|
||
//
|
||
//===----------------------------------------------------------------------===//
|
||
|
||
// MARK: - MetadataValueAttributes storage
|
||
|
||
extension Logger {
|
||
/// Attributes that can be associated with metadata values.
|
||
public struct MetadataValueAttributes: Sendable {
|
||
/// A protocol for defining custom metadata attributes.
|
||
///
|
||
/// Conform to this protocol to define a custom attribute that can be stored in
|
||
/// ``MetadataValueAttributes``. Each conforming type acts as both the key (identified
|
||
/// by its metatype) and the value.
|
||
///
|
||
/// This protocol is designed for **small, fixed-vocabulary attributes**.
|
||
/// Each attribute value is stored as an `Int64` raw value, so attributes occupy minimal
|
||
/// space (one inline slot without heap allocation for the common single-attribute case).
|
||
///
|
||
/// ## Examples
|
||
///
|
||
/// ```swift
|
||
/// public enum Priority: Int64, Sendable, Logger.MetadataValueAttributes.Attribute {
|
||
/// case low = 1
|
||
/// case high = 2
|
||
/// }
|
||
/// ```
|
||
///
|
||
/// ```swift
|
||
/// public struct Priority: Sendable, Hashable, Logger.MetadataValueAttributes.Attribute {
|
||
/// public let rawValue: Int64
|
||
/// public init(rawValue: Int64) {
|
||
/// self.rawValue = rawValue
|
||
/// }
|
||
/// public static let low = Priority(rawValue: 1)
|
||
/// public static let high = Priority(rawValue: 2)
|
||
/// }
|
||
/// ```
|
||
public protocol Attribute: Sendable, RawRepresentable where RawValue == Int64 {}
|
||
|
||
/// An entry in the metadata attributes storage.
|
||
@usableFromInline
|
||
internal struct Entry: Sendable, Equatable {
|
||
@usableFromInline
|
||
internal var key: ObjectIdentifier
|
||
|
||
@usableFromInline
|
||
internal var value: Int64
|
||
|
||
@inlinable
|
||
internal init(key: ObjectIdentifier, value: Int64) {
|
||
self.key = key
|
||
self.value = value
|
||
}
|
||
}
|
||
|
||
@usableFromInline
|
||
internal var _inline: Entry?
|
||
|
||
@usableFromInline
|
||
internal var _overflow: [Entry]?
|
||
|
||
/// Create empty metadata value attributes.
|
||
@inlinable
|
||
public init() {}
|
||
|
||
/// Get or set a custom attribute by its type.
|
||
///
|
||
/// - Parameter attribute: The metatype of the attribute to access.
|
||
/// - Returns: The attribute value, or `nil` if not set.
|
||
@inlinable
|
||
public subscript<Attr: Attribute>(attribute: Attr.Type) -> Attr? {
|
||
get {
|
||
let id = ObjectIdentifier(Attr.self)
|
||
if let inline = self._inline, inline.key == id { return Attr(rawValue: inline.value) }
|
||
if let overflow = self._overflow {
|
||
for entry in overflow {
|
||
if entry.key == id { return Attr(rawValue: entry.value) }
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
set {
|
||
let id = ObjectIdentifier(Attr.self)
|
||
if let v = newValue {
|
||
self._upsert(key: id, value: v.rawValue)
|
||
} else {
|
||
self._remove(key: id)
|
||
}
|
||
}
|
||
}
|
||
|
||
@inlinable
|
||
internal mutating func _upsert(key id: ObjectIdentifier, value: Int64) {
|
||
let entry = Entry(key: id, value: value)
|
||
if let inline = self._inline, inline.key == id {
|
||
self._inline = entry
|
||
return
|
||
}
|
||
if let idx = self._overflow?.firstIndex(where: { $0.key == id }) {
|
||
self._overflow?[idx] = entry
|
||
return
|
||
}
|
||
if self._inline == nil {
|
||
self._inline = entry
|
||
} else {
|
||
if self._overflow == nil {
|
||
self._overflow = [entry]
|
||
} else {
|
||
self._overflow?.append(entry)
|
||
}
|
||
}
|
||
}
|
||
|
||
@inlinable
|
||
internal mutating func _remove(key id: ObjectIdentifier) {
|
||
if let inline = self._inline, inline.key == id {
|
||
if var overflow = self._overflow, !overflow.isEmpty {
|
||
self._inline = overflow.removeLast()
|
||
self._overflow = overflow.isEmpty ? nil : overflow
|
||
} else {
|
||
self._inline = nil
|
||
}
|
||
return
|
||
}
|
||
if let idx = self._overflow?.firstIndex(where: { $0.key == id }) {
|
||
self._overflow?.remove(at: idx)
|
||
if self._overflow?.isEmpty == true {
|
||
self._overflow = nil
|
||
}
|
||
}
|
||
}
|
||
|
||
@inlinable
|
||
internal mutating func _merge(from other: Self) {
|
||
if let inline = other._inline {
|
||
self._upsert(key: inline.key, value: inline.value)
|
||
}
|
||
if let overflow = other._overflow {
|
||
for entry in overflow {
|
||
self._upsert(key: entry.key, value: entry.value)
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Compare all entries as an unordered set.
|
||
///
|
||
/// The inline slot and overflow array may hold the same logical entries in different
|
||
/// positions depending on insertion order. This method checks set equality by
|
||
/// verifying that every entry on one side exists on the other. O(n²) but n is
|
||
/// typically 1–2.
|
||
@inlinable
|
||
internal func _isEqual(to other: Self) -> Bool {
|
||
let lhsOverflowCount = self._overflow?.count ?? 0
|
||
let rhsOverflowCount = other._overflow?.count ?? 0
|
||
let lhsCount = (self._inline != nil ? 1 : 0) + lhsOverflowCount
|
||
let rhsCount = (other._inline != nil ? 1 : 0) + rhsOverflowCount
|
||
guard lhsCount == rhsCount else { return false }
|
||
guard lhsCount > 0 else { return true }
|
||
|
||
// Check that every lhs entry exists in rhs.
|
||
// With matching counts, this is sufficient for set equality.
|
||
if let inline = self._inline {
|
||
if !other._contains(inline) { return false }
|
||
}
|
||
if let overflow = self._overflow {
|
||
for entry in overflow {
|
||
if !other._contains(entry) { return false }
|
||
}
|
||
}
|
||
return true
|
||
}
|
||
|
||
@inlinable
|
||
internal func _contains(_ entry: Entry) -> Bool {
|
||
if self._inline == entry { return true }
|
||
if let overflow = self._overflow {
|
||
for e in overflow {
|
||
if e == entry { return true }
|
||
}
|
||
}
|
||
return false
|
||
}
|
||
}
|
||
}
|
||
|
||
extension Logger.MetadataValueAttributes: Equatable {
|
||
@inlinable
|
||
public static func == (lhs: Self, rhs: Self) -> Bool {
|
||
lhs._isEqual(to: rhs)
|
||
}
|
||
}
|
||
|
||
extension Logger.MetadataValueAttributes: ExpressibleByArrayLiteral {
|
||
/// Creates metadata value attributes from an array literal of attribute values.
|
||
///
|
||
/// Each element is any ``Attribute`` conforming value. The key is
|
||
/// inferred from the concrete type of the value.
|
||
///
|
||
/// ```swift
|
||
/// let attrs: Logger.MetadataValueAttributes = [Sensitivity.sensitive, ValueType.int64]
|
||
/// ```
|
||
/// Each element goes through existential boxing to extract `type(of:)` and `.rawValue`.
|
||
/// This is acceptable for a literal initializer but should not be used in hot paths;
|
||
/// prefer the type-safe subscript (`attrs[SomeAttribute.self] = value`) for performance-sensitive code.
|
||
@inlinable
|
||
public init(arrayLiteral elements: any Logger.MetadataValueAttributes.Attribute...) {
|
||
self.init()
|
||
for element in elements {
|
||
self._upsert(key: ObjectIdentifier(type(of: element)), value: element.rawValue)
|
||
}
|
||
}
|
||
}
|
||
|
||
// MARK: - AttributedStringCarrier
|
||
|
||
extension Logger {
|
||
/// Internal carrier that wraps a string with metadata attributes.
|
||
///
|
||
/// Produced by `MetadataValue.StringInterpolation` when any interpolation
|
||
/// segment specifies attributes, or by ``MetadataValue/attributed(_:attributes:)``.
|
||
/// This is the only type that carries attributes; the `.attributes` property on
|
||
/// `MetadataValue` checks for it with a concrete type comparison rather than a
|
||
/// protocol conformance lookup.
|
||
@usableFromInline
|
||
internal struct AttributedStringCarrier: CustomStringConvertible, Sendable {
|
||
@usableFromInline
|
||
internal let string: String
|
||
|
||
@usableFromInline
|
||
internal let metadataAttributes: Logger.MetadataValueAttributes
|
||
|
||
@usableFromInline
|
||
internal init(string: String, metadataAttributes: Logger.MetadataValueAttributes) {
|
||
self.string = string
|
||
self.metadataAttributes = metadataAttributes
|
||
}
|
||
|
||
@inlinable
|
||
internal var description: String { self.string }
|
||
}
|
||
}
|
||
|
||
// MARK: - MetadataValue attributes API
|
||
|
||
extension Logger.MetadataValue {
|
||
/// The attributes associated with this metadata value, if any.
|
||
///
|
||
/// **Getting:** When the value is a ``stringConvertible(_:)`` wrapping an
|
||
/// `AttributedStringCarrier`, returns that carrier's attributes.
|
||
/// For all other cases returns empty attributes.
|
||
///
|
||
/// **Setting:** Replaces the value with `.stringConvertible(AttributedStringCarrier(...))`
|
||
/// carrying the given attributes. For `.string` and `.stringConvertible` cases the string
|
||
/// representation is preserved. Setting attributes on a `.dictionary` or `.array` value is a
|
||
/// programmer error: it triggers an assertion in debug builds and leaves the value unchanged in
|
||
/// release builds. Set attributes on the leaf values instead.
|
||
///
|
||
/// Only handlers that inspect attributes pay the cost of the getter check.
|
||
@inlinable
|
||
public var attributes: Logger.MetadataValueAttributes {
|
||
get {
|
||
if case .stringConvertible(let box) = self,
|
||
let carrier = box as? Logger.AttributedStringCarrier
|
||
{
|
||
return carrier.metadataAttributes
|
||
}
|
||
return .init()
|
||
}
|
||
set {
|
||
switch self {
|
||
case .string(let s):
|
||
self = .stringConvertible(
|
||
Logger.AttributedStringCarrier(string: s, metadataAttributes: newValue)
|
||
)
|
||
case .stringConvertible(let box):
|
||
self = .stringConvertible(
|
||
Logger.AttributedStringCarrier(string: box.description, metadataAttributes: newValue)
|
||
)
|
||
case .dictionary, .array:
|
||
assertionFailure("Cannot set attributes on .dictionary or .array metadata values")
|
||
return
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Creates an attributed metadata value from a string-convertible value and attributes.
|
||
///
|
||
/// This is a convenience factory that behaves like an additional enum case, producing
|
||
/// a `.stringConvertible(AttributedStringCarrier(...))` value without string interpolation:
|
||
///
|
||
/// ```swift
|
||
/// let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
|
||
/// ```
|
||
@inlinable
|
||
public static func attributed(
|
||
_ value: some CustomStringConvertible & Sendable,
|
||
attributes: Logger.MetadataValueAttributes
|
||
) -> Self {
|
||
.stringConvertible(
|
||
Logger.AttributedStringCarrier(
|
||
string: String(describing: value),
|
||
metadataAttributes: attributes
|
||
)
|
||
)
|
||
}
|
||
}
|
||
|
||
// MARK: - Attributed string interpolation
|
||
|
||
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
|
||
// https://bugs.swift.org/browse/SR-9687
|
||
extension Logger.MetadataValue: ExpressibleByStringInterpolation {
|
||
/// Custom string interpolation that optionally captures metadata attributes.
|
||
///
|
||
/// When no attributes are specified, produces `.string(...)` — identical to the
|
||
/// default `DefaultStringInterpolation` behavior. When any interpolation segment
|
||
/// specifies attributes (via the `attributes:` parameter), the result is
|
||
/// `.stringConvertible(AttributedStringCarrier(...))` carrying both the string
|
||
/// and the accumulated attributes.
|
||
///
|
||
/// Attribute packages (like `LoggingAttributes`) can add overloads with
|
||
/// domain-specific parameters (e.g. `sensitivity:`) that call through to
|
||
/// `appendInterpolation(_:attributes:)`.
|
||
public struct StringInterpolation: StringInterpolationProtocol, Sendable {
|
||
@usableFromInline
|
||
internal var output: String = ""
|
||
|
||
@usableFromInline
|
||
internal var attributes: Logger.MetadataValueAttributes = .init()
|
||
|
||
@usableFromInline
|
||
internal var hasAttributes: Bool = false
|
||
|
||
@inlinable
|
||
public init(literalCapacity: Int, interpolationCount: Int) {
|
||
self.output.reserveCapacity(literalCapacity + interpolationCount * 2)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendLiteral(_ literal: String) {
|
||
self.output.append(literal)
|
||
}
|
||
|
||
@inlinable
|
||
internal mutating func _mergeAttributes(_ attributes: Logger.MetadataValueAttributes) {
|
||
if self.hasAttributes {
|
||
self.attributes._merge(from: attributes)
|
||
} else {
|
||
self.attributes = attributes
|
||
}
|
||
self.hasAttributes = true
|
||
}
|
||
|
||
// MARK: Plain interpolation
|
||
// The four overloads below mirror `DefaultStringInterpolation`'s shape.
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||
_ value: T
|
||
) {
|
||
value.write(to: &self.output)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||
_ value: T
|
||
) {
|
||
value.write(to: &self.output)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||
_ value: T
|
||
) {
|
||
self.output.append(value.description)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T>(
|
||
_ value: T
|
||
) {
|
||
self.output.append(String(describing: value))
|
||
}
|
||
|
||
// MARK: Optional interpolation with a default
|
||
// The four overloads below mirror `DefaultStringInterpolation`'s `default:`
|
||
// shape so that `"\(optional, default: "none")"` keeps working when the
|
||
// literal is inferred as a `Logger.MetadataValue`.
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||
_ value: T?,
|
||
default defaultValue: @autoclosure () -> some StringProtocol
|
||
) {
|
||
if let value {
|
||
self.appendInterpolation(value)
|
||
} else {
|
||
self.output.append(String(defaultValue()))
|
||
}
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||
_ value: T?,
|
||
default defaultValue: @autoclosure () -> some StringProtocol
|
||
) {
|
||
if let value {
|
||
self.appendInterpolation(value)
|
||
} else {
|
||
self.output.append(String(defaultValue()))
|
||
}
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||
_ value: T?,
|
||
default defaultValue: @autoclosure () -> some StringProtocol
|
||
) {
|
||
if let value {
|
||
self.appendInterpolation(value)
|
||
} else {
|
||
self.output.append(String(defaultValue()))
|
||
}
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T>(
|
||
_ value: T?,
|
||
default defaultValue: @autoclosure () -> some StringProtocol
|
||
) {
|
||
if let value {
|
||
self.appendInterpolation(value)
|
||
} else {
|
||
self.output.append(String(defaultValue()))
|
||
}
|
||
}
|
||
|
||
// MARK: Interpolation with a custom attributes closure
|
||
//
|
||
// ```swift
|
||
// "\(userId, attributes: { $0[MyAttribute.self] = .flagged })"
|
||
// ```
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||
_ value: T,
|
||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||
) {
|
||
value.write(to: &self.output)
|
||
attributes(&self.attributes)
|
||
self.hasAttributes = true
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||
_ value: T,
|
||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||
) {
|
||
value.write(to: &self.output)
|
||
attributes(&self.attributes)
|
||
self.hasAttributes = true
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||
_ value: T,
|
||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||
) {
|
||
self.output.append(value.description)
|
||
attributes(&self.attributes)
|
||
self.hasAttributes = true
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T>(
|
||
_ value: T,
|
||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||
) {
|
||
self.output.append(String(describing: value))
|
||
attributes(&self.attributes)
|
||
self.hasAttributes = true
|
||
}
|
||
|
||
// MARK: Interpolation with pre-built attributes
|
||
//
|
||
// ```swift
|
||
// "\(userId, attributes: [Sensitivity.sensitive])"
|
||
// ```
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||
_ value: T,
|
||
attributes: Logger.MetadataValueAttributes
|
||
) {
|
||
value.write(to: &self.output)
|
||
self._mergeAttributes(attributes)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||
_ value: T,
|
||
attributes: Logger.MetadataValueAttributes
|
||
) {
|
||
value.write(to: &self.output)
|
||
self._mergeAttributes(attributes)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||
_ value: T,
|
||
attributes: Logger.MetadataValueAttributes
|
||
) {
|
||
self.output.append(value.description)
|
||
self._mergeAttributes(attributes)
|
||
}
|
||
|
||
@inlinable
|
||
public mutating func appendInterpolation<T>(
|
||
_ value: T,
|
||
attributes: Logger.MetadataValueAttributes
|
||
) {
|
||
self.output.append(String(describing: value))
|
||
self._mergeAttributes(attributes)
|
||
}
|
||
}
|
||
|
||
/// Creates a metadata value from string interpolation.
|
||
///
|
||
/// If any interpolation segment specified attributes, the result is
|
||
/// `.stringConvertible(AttributedStringCarrier(...))`. Otherwise, `.string(...)`.
|
||
@inlinable
|
||
public init(stringInterpolation: StringInterpolation) {
|
||
if stringInterpolation.hasAttributes {
|
||
self = .stringConvertible(
|
||
Logger.AttributedStringCarrier(
|
||
string: stringInterpolation.output,
|
||
metadataAttributes: stringInterpolation.attributes
|
||
)
|
||
)
|
||
} else {
|
||
self = .string(stringInterpolation.output)
|
||
}
|
||
}
|
||
}
|