From 67d578101946e0358809f7d563d362b23b189aff Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 19 Oct 2020 17:09:30 -0400 Subject: [PATCH] feat: add keys operation to getter (#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 | 2 +- api/src/api/propagation.ts | 14 +-- .../propagation/NoopTextMapPropagator.ts | 4 +- .../context/propagation/TextMapPropagator.ts | 89 +++++++++++++++++-- api/src/context/propagation/getter.ts | 31 ------- api/src/context/propagation/setter.ts | 31 ------- api/src/index.ts | 2 - 7 files changed, 92 insertions(+), 81 deletions(-) delete mode 100644 api/src/context/propagation/getter.ts delete mode 100644 api/src/context/propagation/setter.ts diff --git a/api/src/api/global-utils.ts b/api/src/api/global-utils.ts index 407399c8fbc..87791f2817a 100644 --- a/api/src/api/global-utils.ts +++ b/api/src/api/global-utils.ts @@ -65,4 +65,4 @@ export function makeGetter( * 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; diff --git a/api/src/api/propagation.ts b/api/src/api/propagation.ts index 3e39ab1ff0c..76b6ef57fa8 100644 --- a/api/src/api/propagation.ts +++ b/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, - setter: SetterFunction = defaultSetter, + setter: TextMapSetter = defaultTextMapSetter, context: Context = contextApi.active() ): void { return this._getGlobalPropagator().inject(context, carrier, setter); @@ -89,7 +93,7 @@ export class PropagationAPI { */ public extract( carrier: Carrier, - getter: GetterFunction = defaultGetter, + getter: TextMapGetter = defaultTextMapGetter, context: Context = contextApi.active() ): Context { return this._getGlobalPropagator().extract(context, carrier, getter); diff --git a/api/src/context/propagation/NoopTextMapPropagator.ts b/api/src/context/propagation/NoopTextMapPropagator.ts index c2155fadc98..06105496f61 100644 --- a/api/src/context/propagation/NoopTextMapPropagator.ts +++ b/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; } } diff --git a/api/src/context/propagation/TextMapPropagator.ts b/api/src/context/propagation/TextMapPropagator.ts index f56112495d7..52960612d86 100644 --- a/api/src/context/propagation/TextMapPropagator.ts +++ b/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 { /** * 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 + ): 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 + ): 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 { + /** + * 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 { + /** + * 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; + }, +}; diff --git a/api/src/context/propagation/getter.ts b/api/src/context/propagation/getter.ts deleted file mode 100644 index 75650107284..00000000000 --- a/api/src/context/propagation/getter.ts +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright The OpenTelemetry Authors - * - * 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 - * - * https://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. - */ - -export type GetterFunction = ( - carrier: Carrier, - key: string -) => unknown; - -/** - * Default getter which just does a simple property access. Returns - * undefined if the key is not set. - * - * @param carrier - * @param key - */ -export function defaultGetter(carrier: any, key: string): unknown { - return carrier[key]; -} diff --git a/api/src/context/propagation/setter.ts b/api/src/context/propagation/setter.ts deleted file mode 100644 index 2eb56adf46f..00000000000 --- a/api/src/context/propagation/setter.ts +++ /dev/null @@ -1,31 +0,0 @@ -/* - * Copyright The OpenTelemetry Authors - * - * 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 - * - * https://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. - */ - -export type SetterFunction = ( - carrier: Carrier, - key: string, - value: unknown -) => void; - -/** - * Default setter which sets value via direct property access - * - * @param carrier - * @param key - */ -export function defaultSetter(carrier: any, key: string, value: unknown) { - carrier[key] = value; -} diff --git a/api/src/index.ts b/api/src/index.ts index 02a257f0b52..e290b8a6c7e 100644 --- a/api/src/index.ts +++ b/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';