Immutable injection in TextMapPropagator

core/common/src/main/scala/org/typelevel/otel4s/TextMapPropagator.scala

@@ -53,8 +53,8 @@ trait TextMapPropagator[F[_]] {
     */
   def extract[A: TextMapGetter](ctx: Vault, carrier: A): Vault
 
-  /** Injects data from the context into the given `carrier` for downstream
-    * consumers, for example as HTTP headers.
+  /** Injects data from the context into the given mutable `carrier` for
+    * downstream consumers, for example as HTTP headers.
     *
     * @param ctx
     *   the context containing the value to be injected
@@ -63,9 +63,29 @@ trait TextMapPropagator[F[_]] {
     *   holds propagation fields
     *
     * @tparam A
-    *   the type of the carrier
+    *   the type of the carrier, which is mutable
     */
   def inject[A: TextMapSetter](ctx: Vault, carrier: A): F[Unit]
+
+  /** Injects data from the context into a copy of the given immutable `carrier`
+    * for downstream consumers, for example as HTTP headers.
+    *
+    * This method is an extension to the OpenTelemetry specification to support
+    * immutable carrier types.
+    *
+    * @param ctx
+    *   the context containing the value to be injected
+    *
+    * @param carrier
+    *   holds propagation fields
+    *
+    * @tparam A
+    *   the type of the carrier
+    *
+    * @return
+    *   a copy of the carrier, with new fields injected
+    */
+  def injected[A: TextMapUpdater](ctx: Vault, carrier: A): A
 }
 
 object TextMapPropagator {
@@ -79,5 +99,8 @@ object TextMapPropagator {
 
       def inject[A: TextMapSetter](ctx: Vault, carrier: A): F[Unit] =
         Applicative[F].unit
+
+      def injected[A: TextMapUpdater](ctx: Vault, carrier: A): A =
+        carrier
     }
 }

core/common/src/main/scala/org/typelevel/otel4s/TextMapUpdater.scala

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2022 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.typelevel.otel4s
+
+trait TextMapUpdater[A] {
+  def updated(carrier: A, key: String, value: String): A
+}

java/common/src/main/scala/org/typelevel/otel4s/java/TextMapPropagatorImpl.scala

@@ -39,4 +39,18 @@ private[java] class TextMapPropagatorImpl[F[_]: Sync](
     Sync[F].delay(
       jPropagator.inject(toJContext(ctx), carrier, fromTextMapSetter)
     )
+
+  def injected[A](ctx: Vault, carrier: A)(implicit
+      injector: TextMapUpdater[A]
+  ): A = {
+    var injectedCarrier = carrier
+    jPropagator.inject[Null](
+      toJContext(ctx),
+      null, // explicitly allowed per opentelemetry-java, so our setter can be a lambda!
+      (_, key, value) => {
+        injectedCarrier = injector.updated(injectedCarrier, key, value)
+      }
+    )
+    injectedCarrier
+  }
 }