swift-service-context

1.0.0

Minimal type-safe context propagation container
apple/swift-service-context

What's New

1.0.0

2023-05-31T19:37:09Z

1.0.0: ServiceContext

Please note that the primary module vended by this library is ServiceContext which has changed from the library's pre-1.0 days.

Please continue reading about migrating from the "Baggage" name type if you were using this library from before its 1.0 days.

Migrating off the legacy type name: "Baggage"

This package was initially developed for quite a while as the swift-distributed-tracing-baggage package and was used only by the swift-distributed-tracing project. As time passed, more projects were making use of the baggage type and we decided to name this more generically.

Previously: code using Baggage directly would be using it like this:

import InstrumentationBaggage

private enum FirstTestKey: BaggageKey {
    typealias Value = Int
}

var baggage = Baggage.topLevel // Note, from 1.0 this will emit deprecation warnings
guard let value = baggage[FirstTestKey.self] else {
  return "no value"
}
return "value was: \(value)"

The above snippet continues to work, however it is deprecated upon release.

Please adopt the new spelling of the type, which has the same capabilities as previous type:

import ServiceContextModule

private enum FirstTestKey: ServiceContextKey {
    typealias Value = Int
}

var context = ServiceContext.topLevel
guard let value = context[FirstTestKey.self] else {
  return "no value"
}
return "value was: \(value)"

Everything about ServiceContext is the same as it was with Baggage, and the InstrumentationBaggage module now simply has a typealias Baggage = ServiceContext to ease migration in case you were using this type directly.

The more generic name of "service context" allows developers to use this type for various context propagation needs, without necessarily binding it all with distributed tracing and the baggage terminology.

What's Changed

  • Add .spi.yml for Swift Package Index DocC support by @yim-lee in #29
  • Add CI for Swift 5.8 and update nightly to Ubuntu 22.04 by @yim-lee in #32
  • Update CoC and add CONTRIBUTING file by @ktoso in #33
  • Update CI by @yim-lee in #34
  • Add _unsafeInheritExecutor to withValue convenience func by @ktoso in #35
  • Add test coverage for using withValue inside an actor by @ktoso in #37
  • Change package to ServiceContext; keep baggage compat module by @ktoso in #38
  • Readme update for 1.0 by @ktoso in #39

Full Changelog: 0.4.1...1.0.0

Swift Service Context

Swift 5.1 Swift 5.2 Swift 5.3 Swift 5.4 Swift 5.5 Swift 5.6 Swift 5.7

ServiceContext is a minimal (zero-dependency) context propagation container, intended to "carry" items for purposes of cross-cutting tools to be built on top of it.

It is modeled after the concepts explained in W3C Baggage and the in the spirit of Tracing Plane 's "Baggage Context" type, although by itself it does not define a specific serialization format.

See https://github.com/apple/swift-distributed-tracing for actual instrument types and implementations which can be used to deploy various cross-cutting instruments all reusing the same baggage type. More information can be found in the SSWG meeting notes.

Overview

ServiceContext serves as currency type for carrying around additional contextual information between Swift tasks and functions.

One generally starts from a "top level" (empty) or the "current" (ServiceContext.current) context and then adds values to it.

The context is a value type and is propagated using task-local values so it can be safely used from concurrent contexts like this:

var context = ServiceContext.topLevel
context[FirstTestKey.self] = 42

func exampleFunction() async -> Int {
    guard let context = ServiceContext.current {
        return 0
    }
    guard let value = context[FirstTestKey.self] {
        return 0
    }
    print("test = \(value)") // test = 42
    return value
}

let c = ServiceContext.withValue(context) {
    await exampleFunction()
}
assert(c == 42)

ServiceContext is a fundamental building block for how distributed tracing propagages trace identifiers.

Dependency

In order to depend on this library you can use the Swift Package Manager, and add the following dependency to your Package.swift:

dependencies: [
  .package(
    url: "https://github.com/apple/swift-service-context.git",
    from: "1.0.0"
  )
]

and depend on the module in your target:

targets: [
    .target(
        name: "MyAwesomeApp",
        dependencies: [
            .product(
              name: "ServiceContextModule",
              package: "swift-service-context"
            ),
        ]
    ),
    // ...
]

Contributing

Please make sure to run the ./scripts/soundness.sh script when contributing, it checks formatting and similar things.

You can ensure it always runs and passes before you push by installing a pre-push hook with git:

echo './scripts/soundness.sh' > .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Description

  • Swift Tools 5.6.0
View More Packages from this Author

Dependencies

Last updated: Sun Mar 24 2024 13:59:37 GMT-0900 (Hawaii-Aleutian Daylight Time)