feat: add keys operation to getter (open-telemetry#1576)

* feat: add keys operation to getter

* chore: lint

* chore: rename getter/setter to TextMapGetter/Setter

* chore: lint

* chore: use setter in fetch plugin

* chore: lint

* chore: remove logs

api/src/api/global-utils.ts

@@ -65,4 +65,4 @@ export function makeGetter<T>(
  * version. If the global API is not compatible with the API package
  * attempting to get it, a NOOP API implementation will be returned.
  */
-export const API_BACKWARDS_COMPATIBILITY_VERSION = 0;
+export const API_BACKWARDS_COMPATIBILITY_VERSION = 1;

api/src/api/propagation.ts

@@ -15,10 +15,14 @@
  */
 
 import { Context } from '@opentelemetry/context-base';
-import { defaultGetter, GetterFunction } from '../context/propagation/getter';
-import { TextMapPropagator } from '../context/propagation/TextMapPropagator';
 import { NOOP_TEXT_MAP_PROPAGATOR } from '../context/propagation/NoopTextMapPropagator';
-import { defaultSetter, SetterFunction } from '../context/propagation/setter';
+import {
+  defaultTextMapGetter,
+  defaultTextMapSetter,
+  TextMapGetter,
+  TextMapPropagator,
+  TextMapSetter,
+} from '../context/propagation/TextMapPropagator';
 import { ContextAPI } from './context';
 import {
   API_BACKWARDS_COMPATIBILITY_VERSION,
@@ -74,7 +78,7 @@ export class PropagationAPI {
    */
   public inject<Carrier>(
     carrier: Carrier,
-    setter: SetterFunction<Carrier> = defaultSetter,
+    setter: TextMapSetter<Carrier> = defaultTextMapSetter,
     context: Context = contextApi.active()
   ): void {
     return this._getGlobalPropagator().inject(context, carrier, setter);
@@ -89,7 +93,7 @@ export class PropagationAPI {
    */
   public extract<Carrier>(
     carrier: Carrier,
-    getter: GetterFunction<Carrier> = defaultGetter,
+    getter: TextMapGetter<Carrier> = defaultTextMapGetter,
     context: Context = contextApi.active()
   ): Context {
     return this._getGlobalPropagator().extract(context, carrier, getter);

api/src/context/propagation/NoopTextMapPropagator.ts

@@ -22,9 +22,9 @@ import { TextMapPropagator } from './TextMapPropagator';
  */
 export class NoopTextMapPropagator implements TextMapPropagator {
   /** Noop inject function does nothing */
-  inject(context: Context, carrier: unknown, setter: Function): void {}
+  inject(context: Context, carrier: unknown): void {}
   /** Noop extract function does nothing and returns the input context */
-  extract(context: Context, carrier: unknown, getter: Function): Context {
+  extract(context: Context, carrier: unknown): Context {
     return context;
   }
 }

api/src/context/propagation/TextMapPropagator.ts

@@ -15,8 +15,6 @@
  */
 
 import { Context } from '@opentelemetry/context-base';
-import { SetterFunction } from './setter';
-import { GetterFunction } from './getter';
 
 /**
  * Injects `Context` into and extracts it from carriers that travel
@@ -29,7 +27,7 @@ import { GetterFunction } from './getter';
  * usually implemented via library-specific request interceptors, where the
  * client-side injects values and the server-side extracts them.
  */
-export interface TextMapPropagator {
+export interface TextMapPropagator<Carrier = any> {
   /**
    * Injects values from a given `Context` into a carrier.
    *
@@ -40,10 +38,14 @@ export interface TextMapPropagator {
    *     the wire.
    * @param carrier the carrier of propagation fields, such as http request
    *     headers.
-   * @param setter a function which accepts a carrier, key, and value, which
-   *     sets the key on the carrier to the value.
+   * @param setter an optional {@link TextMapSetter}. If undefined, values will be
+   *     set by direct object assignment.
    */
-  inject(context: Context, carrier: unknown, setter: SetterFunction): void;
+  inject(
+    context: Context,
+    carrier: Carrier,
+    setter: TextMapSetter<Carrier>
+  ): void;
 
   /**
    * Given a `Context` and a carrier, extract context values from a
@@ -54,8 +56,77 @@ export interface TextMapPropagator {
    *     the wire.
    * @param carrier the carrier of propagation fields, such as http request
    *     headers.
-   * @param getter a function which accepts a carrier and a key, and returns
-   *     the value from the carrier identified by the key.
+   * @param getter an optional {@link TextMapGetter}. If undefined, keys will be all
+   *     own properties, and keys will be accessed by direct object access.
    */
-  extract(context: Context, carrier: unknown, getter: GetterFunction): Context;
+  extract(
+    context: Context,
+    carrier: Carrier,
+    getter: TextMapGetter<Carrier>
+  ): Context;
 }
+
+/**
+ * A setter is specified by the caller to define a specific method
+ * to set key/value pairs on the carrier within a propagator.
+ */
+export interface TextMapSetter<Carrier = any> {
+  /**
+   * Callback used to set a key/value pair on an object.
+   *
+   * Should be called by the propagator each time a key/value pair
+   * should be set, and should set that key/value pair on the propagator.
+   *
+   * @param carrier object or class which carries key/value pairs
+   * @param key string key to modify
+   * @param value value to be set to the key on the carrier
+   */
+  set(carrier: Carrier, key: string, value: string): void;
+}
+
+/**
+ * A getter is specified by the caller to define a specific method
+ * to get the value of a key from a carrier.
+ */
+export interface TextMapGetter<Carrier = any> {
+  /**
+   * Get a list of all keys available on the carrier.
+   *
+   * @param carrier
+   */
+  keys(carrier: Carrier): string[];
+
+  /**
+   * Get the value of a specific key from the carrier.
+   *
+   * @param carrier
+   * @param key
+   */
+  get(carrier: Carrier, key: string): undefined | string | string[];
+}
+
+export const defaultTextMapGetter: TextMapGetter = {
+  get(carrier, key) {
+    if (carrier == null) {
+      return undefined;
+    }
+    return carrier[key];
+  },
+
+  keys(carrier) {
+    if (carrier == null) {
+      return [];
+    }
+    return Object.keys(carrier);
+  },
+};
+
+export const defaultTextMapSetter: TextMapSetter = {
+  set(carrier, key, value) {
+    if (carrier == null) {
+      return;
+    }
+
+    carrier[key] = value;
+  },
+};

api/src/index.ts

@@ -18,10 +18,8 @@ export * from './common/Exception';
 export * from './common/Logger';
 export * from './common/Time';
 export * from './context/context';
-export * from './context/propagation/getter';
 export * from './context/propagation/TextMapPropagator';
 export * from './context/propagation/NoopTextMapPropagator';
-export * from './context/propagation/setter';
 export * from './correlation_context/CorrelationContext';
 export * from './correlation_context/EntryValue';
 export * from './metrics/BatchObserverResult';