@gitpod/gitpod-protocol 0.1.5-se-workspace-for-teams.10 → 0.1.5-se-workspaceid.6

package/src/util/logging.ts

@@ -30,66 +30,66 @@ export interface LogPayload {
 };
 
 export namespace log {
-    export function error(context: LogContext, message: string, error: Error, payload: LogPayload): void;
-    export function error(context: LogContext, message: string, error: Error): void;
+    export function error(context: LogContext, message: string, error: any, payload: LogPayload): void;
+    export function error(context: LogContext, message: string, error: any): void;
     export function error(context: LogContext, message: string, payload: LogPayload): void;
     export function error(context: LogContext, message: string): void;
-    export function error(context: LogContext, error: Error, payload: LogPayload): void;
-    export function error(context: LogContext, error: Error): void;
-    export function error(message: string, error: Error, payload: LogPayload): void;
-    export function error(message: string, error: Error): void;
+    export function error(context: LogContext, error: any, payload: LogPayload): void;
+    export function error(context: LogContext, error: any): void;
+    export function error(message: string, error: any, payload: LogPayload): void;
+    export function error(message: string, error: any): void;
     export function error(message: string, payload: LogPayload): void;
     export function error(message: string): void;
-    export function error(error: Error, payload: LogPayload): void;
-    export function error(error: Error): void;
+    export function error(error: any, payload: LogPayload): void;
+    export function error(error: any): void;
     export function error(...args: any[]): void {
         errorLog(false, args);
     }
 
-    export function warn(context: LogContext, message: string, error: Error, payload: LogPayload): void;
-    export function warn(context: LogContext, message: string, error: Error): void;
+    export function warn(context: LogContext, message: string, error: any, payload: LogPayload): void;
+    export function warn(context: LogContext, message: string, error: any): void;
     export function warn(context: LogContext, message: string, payload: LogPayload): void;
     export function warn(context: LogContext, message: string): void;
-    export function warn(context: LogContext, error: Error, payload: LogPayload): void;
-    export function warn(context: LogContext, error: Error): void;
-    export function warn(message: string, error: Error, payload: LogPayload): void;
-    export function warn(message: string, error: Error): void;
+    export function warn(context: LogContext, error: any, payload: LogPayload): void;
+    export function warn(context: LogContext, error: any): void;
+    export function warn(message: string, error: any, payload: LogPayload): void;
+    export function warn(message: string, error: any): void;
     export function warn(message: string, payload: LogPayload): void;
     export function warn(message: string): void;
-    export function warn(error: Error, payload: LogPayload): void;
-    export function warn(error: Error): void;
+    export function warn(error: any, payload: LogPayload): void;
+    export function warn(error: any): void;
     export function warn(...args: any[]): void {
         warnLog(false, args);
     }
 
-    export function info(context: LogContext, message: string, error: Error, payload: LogPayload): void;
-    export function info(context: LogContext, message: string, error: Error): void;
+    export function info(context: LogContext, message: string, error: any, payload: LogPayload): void;
+    export function info(context: LogContext, message: string, error: any): void;
     export function info(context: LogContext, message: string, payload: LogPayload): void;
     export function info(context: LogContext, message: string): void;
-    export function info(context: LogContext, error: Error, payload: LogPayload): void;
-    export function info(context: LogContext, error: Error): void;
-    export function info(message: string, error: Error, payload: LogPayload): void;
-    export function info(message: string, error: Error): void;
+    export function info(context: LogContext, error: any, payload: LogPayload): void;
+    export function info(context: LogContext, error: any): void;
+    export function info(message: string, error: any, payload: LogPayload): void;
+    export function info(message: string, error: any): void;
     export function info(message: string, payload: LogPayload): void;
     export function info(message: string): void;
-    export function info(error: Error, payload: LogPayload): void;
-    export function info(error: Error): void;
+    export function info(error: any, payload: LogPayload): void;
+    export function info(error: any): void;
     export function info(...args: any[]): void {
         infoLog(false, args);
     }
 
-    export function debug(context: LogContext, message: string, error: Error, payload: LogPayload): void;
-    export function debug(context: LogContext, message: string, error: Error): void;
+    export function debug(context: LogContext, message: string, error: any, payload: LogPayload): void;
+    export function debug(context: LogContext, message: string, error: any): void;
     export function debug(context: LogContext, message: string, payload: LogPayload): void;
     export function debug(context: LogContext, message: string): void;
-    export function debug(context: LogContext, error: Error, payload: LogPayload): void;
-    export function debug(context: LogContext, error: Error): void;
-    export function debug(message: string, error: Error, payload: LogPayload): void;
-    export function debug(message: string, error: Error): void;
+    export function debug(context: LogContext, error: any, payload: LogPayload): void;
+    export function debug(context: LogContext, error: any): void;
+    export function debug(message: string, error: any, payload: LogPayload): void;
+    export function debug(message: string, error: any): void;
     export function debug(message: string, payload: LogPayload): void;
     export function debug(message: string): void;
-    export function debug(error: Error, payload: LogPayload): void;
-    export function debug(error: Error): void;
+    export function debug(error: any, payload: LogPayload): void;
+    export function debug(error: any): void;
     export function debug(...args: any[]): void {
         debugLog(false, args);
     }
@@ -107,24 +107,32 @@ export namespace log {
     export function setLogLevel(logLevel: LogrusLogLevel | undefined) {
         jsonLogging = true;
 
-        const noop = () => {};
-        const setLog = (logFunc: (calleViaConsole: boolean, args: any[]) => void, funcLvl: LogrusLogLevel): (() => void) => {
-            if (LogrusLogLevel.isGreatherOrEqual(funcLvl, logLevel)) {
-                return function (...args: any[]): void {
-                    logFunc(true, args);
-                };
-            } else {
-                return noop;
-            }
-        };
-
-        console.error = setLog(errorLog, "error");
-        console.warn = setLog(warnLog, "warning");
-        console.info = setLog(infoLog, "info");
-        console.debug = setLog(debugLog, "debug");
+        console.error = function (...args: any[]): void {
+            errorLog(true, args);
+        }
+        console.warn = function (...args: any[]): void {
+            warnLog(true, args);
+        }
+        console.info = function (...args: any[]): void {
+            infoLog(true, args);
+        }
+        console.debug = function (...args: any[]): void {
+            debugLog(true, args);
+        }
 
         console.log = console.info;
         // FIXME wrap also other console methods (e.g. trace())
+
+        // set/unset log functions based on loglevel so we only have to evaluate once, not every call
+        const noop = () => {};
+        const setLog = (logFunc: DoLogFunction, funcLevel: LogrusLogLevel): DoLogFunction => {
+            return LogrusLogLevel.isGreatherOrEqual(funcLevel, logLevel) ? logFunc : noop;
+        };
+
+        errorLog = setLog(doErrorLog, "error");
+        warnLog = setLog(doWarnLog, "warning");
+        infoLog = setLog(doInfoLog, "info");
+        debugLog = setLog(doDebugLog, "debug");
     }
 
     export function resetToDefaultLogging(): void {
@@ -142,19 +150,25 @@ export namespace log {
     }
 }
 
-function errorLog(calledViaConsole: boolean, args: any[]): void {
+type DoLogFunction = (calledViaConsole: boolean, args: any[]) => void;
+
+let errorLog = doErrorLog;
+function doErrorLog(calledViaConsole: boolean, args: any[]): void {
     doLog(calledViaConsole, errorConsoleLog, 'ERROR', args);
 }
 
-function warnLog(calledViaConsole: boolean, args: any[]): void {
+let warnLog = doWarnLog;
+function doWarnLog(calledViaConsole: boolean, args: any[]): void {
     doLog(calledViaConsole, warnConsoleLog, 'WARNING', args);
 }
 
-function infoLog(calledViaConsole: boolean, args: any[]): void {
+let infoLog = doInfoLog;
+function doInfoLog(calledViaConsole: boolean, args: any[]): void {
     doLog(calledViaConsole, infoConsoleLog, 'INFO', args);
 }
 
-function debugLog(calledViaConsole: boolean, args: any[]): void {
+let debugLog = doDebugLog;
+function doDebugLog(calledViaConsole: boolean, args: any[]): void {
     doLog(calledViaConsole, debugConsoleLog, 'DEBUG', args);
 }
 
@@ -294,7 +308,6 @@ function makeLogItem(severity: GoogleLogSeverity, context: LogContext | undefine
         severity,
         time: new Date().toISOString(),
         environment: process.env.KUBE_STAGE,
-        region: process.env.GITPOD_REGION,
         context,
         message,
         error,

package/src/util/parse-workspace-id.spec.ts

@@ -6,7 +6,7 @@
 
 import * as chai from 'chai';
 import { suite, test } from 'mocha-typescript';
-import { parseWorkspaceIdFromHostname } from './parse-workspace-id';
+import { matchesInstanceIdOrLegacyWorkspaceIdExactly, matchesNewWorkspaceIdExactly, parseWorkspaceIdFromHostname } from './parse-workspace-id';
 const expect = chai.expect;
 
 @suite
@@ -52,5 +52,25 @@ export class ParseWorkspaceIdTest {
         const actual = parseWorkspaceIdFromHostname("webview-3000-ca81a50f-09d7-465c-acd9-264a747d5351.ws-eu01.some.subdomain.somehost.com");
         expect(actual).to.equal("ca81a50f-09d7-465c-acd9-264a747d5351");
     }
+
+    // match - instance ID
+    @test public matchesInstanceIdOrLegacyWorkspaceIdExactly_positive() {
+        const actual = matchesInstanceIdOrLegacyWorkspaceIdExactly("b7e0eaf8-ec73-44ec-81ea-04859263b656");
+        expect(actual).to.be.true;
+    }
+    @test public matchesInstanceIdOrLegacyWorkspaceIdExactly_negative() {
+        const actual = matchesInstanceIdOrLegacyWorkspaceIdExactly("b7e0eaf8-ec73-44ec-81a-04859263b656");
+        expect(actual).to.be.false;
+    }
+
+    // match - new workspace ID
+    @test public matchesWorkspaceIdExactly_new_positive() {
+        const actual = matchesNewWorkspaceIdExactly("moccasin-ferret-155799b3");
+        expect(actual).to.be.true;
+    }
+    @test public matchesWorkspaceIdExactly_new_negative() {
+        const actual = matchesNewWorkspaceIdExactly("moccasin-ferret-15599b3");
+        expect(actual).to.be.false;
+    }
 }
 module.exports = new ParseWorkspaceIdTest()

package/src/util/parse-workspace-id.ts

@@ -4,6 +4,14 @@
  * See License-AGPL.txt in the project root for license information.
  */
 
+const REGEX_WORKSPACE_ID = /[0-9a-z]{2,16}-[0-9a-z]{2,16}-[0-9a-z]{8}/;
+const REGEX_WORKSPACE_ID_EXACT = new RegExp(`^${REGEX_WORKSPACE_ID.source}$`);
+// We need to parse the workspace id precisely here to get the case '<some-str>-<port>-<wsid>.ws.' right
+const REGEX_WORKSPACE_ID_FROM_HOSTNAME = new RegExp(`(${REGEX_WORKSPACE_ID.source})\.ws`);
+
+const REGEX_WORKSPACE_ID_LEGACY = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/;
+const REGEX_WORKSPACE_ID_LEGACY_EXACT = new RegExp(`^${REGEX_WORKSPACE_ID_LEGACY.source}$`);
+const REGEX_WORKSPACE_ID_LEGACY_FROM_HOSTNAME = new RegExp(`(${REGEX_WORKSPACE_ID_LEGACY.source})\.ws`);
 
 /**
  * Hostname may be of the form:
@@ -13,17 +21,35 @@
  * @param hostname The hostname the request is headed to
  */
 export const parseWorkspaceIdFromHostname = function(hostname: string) {
-    // We need to parse the workspace id precisely here to get the case '<some-str>-<port>-<wsid>.ws.' right
-    const wsIdExpression = /([0-9a-z]{2,16}-[0-9a-z]{2,16}-[0-9a-z]{8})\.ws/g;
-    const match = wsIdExpression.exec(hostname);
+    const match = REGEX_WORKSPACE_ID_FROM_HOSTNAME.exec(hostname);
     if (match && match.length >= 2) {
         return match[1];
     } else {
-        const legacyUrlFormat = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.ws/g;
-        const legacyMatch = legacyUrlFormat.exec(hostname);
+        const legacyMatch = REGEX_WORKSPACE_ID_LEGACY_FROM_HOSTNAME.exec(hostname);
         if (legacyMatch && legacyMatch.length >= 2) {
             return legacyMatch[1];
         }
         return undefined;
     }
-}
+};
+
+/** Equalls UUIDv4 (and REGEX_WORKSPACE_ID_LEGACY!) */
+const REGEX_INSTANCE_ID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/;
+const REGEX_INSTANCE_ID_EXACT = new RegExp(`^${REGEX_INSTANCE_ID.source}$`);
+
+/**
+ * @param maybeId
+ * @returns
+ */
+export const matchesInstanceIdOrLegacyWorkspaceIdExactly = function(maybeId: string): boolean {
+    return REGEX_INSTANCE_ID_EXACT.test(maybeId)
+        || REGEX_WORKSPACE_ID_LEGACY_EXACT.test(maybeId);
+};
+
+/**
+ * @param maybeWorkspaceId
+ * @returns
+ */
+export const matchesNewWorkspaceIdExactly = function(maybeWorkspaceId: string): boolean {
+    return REGEX_WORKSPACE_ID_EXACT.test(maybeWorkspaceId);
+};

package/src/util/repeat.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2021 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License-AGPL.txt in the project root for license information.
+ */
+
+import { Disposable } from "..";
+import { log } from "./logging";
+
+/**
+ * This intends to be a drop-in replacement for 'setInterval' implemented with a 'setTimeout' chain
+ * to ensure we're not creating more timeouts than we can process.
+ * @param op
+ * @param everyMilliseconds
+ * @returns
+ */
+export function repeat(op: () => Promise<void> | void, everyMilliseconds: number): Disposable {
+    let timer: NodeJS.Timeout | undefined = undefined;
+    let stopped = false;
+    const repeated = () => {
+        if (stopped) {
+            // in case we missed the clearTimeout i 'await'
+            return;
+        }
+
+        timer = setTimeout(async () => {
+            try {
+                await op();
+            } catch (err) {
+                // catch error here to
+                log.error(err);
+            }
+
+            repeated(); // chain ourselves - after the 'await'
+        }, everyMilliseconds);
+    };
+    repeated();
+
+    return Disposable.create(() => {
+        stopped = true;
+        if (timer) {
+            clearTimeout(timer);
+        }
+    });
+}

package/src/util/tracing.spec.ts

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2021 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License-AGPL.txt in the project root for license information.
+ */
+
+import { suite, test } from "mocha-typescript"
+import * as chai from "chai"
+import { TraceContext } from "./tracing";
+import { MockTracer } from "opentracing";
+
+const expect = chai.expect
+
+@suite class TestTracing {
+
+    @test public async testTracingContext_addNestedTags() {
+        const tracer = new MockTracer();
+        const span = tracer.startSpan('testTracingContext_addNestedTags');
+        TraceContext.addNestedTags({ span }, {
+            rpc: {
+                system: "jsonrpc",
+                jsonrpc: {
+                    version: "1.0",
+                    method: "test",
+                    parameters: ["abc", "def"],
+                },
+            },
+        });
+
+        const mockSpan = tracer.report().spans[0];
+        expect(mockSpan.tags()).to.deep.equal({
+            "rpc.system": "jsonrpc",
+            "rpc.jsonrpc.version": "1.0",
+            "rpc.jsonrpc.method": "test",
+            "rpc.jsonrpc.parameters.0": "abc",
+            "rpc.jsonrpc.parameters.1": "def",
+        });
+    }
+
+    @test public async testTracingContext_addNestedTags_null() {
+        const tracer = new MockTracer();
+        const span = tracer.startSpan('testTracingContext_addNestedTags_null');
+        TraceContext.addNestedTags({ span }, {
+            someShape: {
+                thisIsNull: null,
+                thisIsUndefined: undefined,
+            },
+        });
+
+        const mockSpan = tracer.report().spans[0];
+        expect(mockSpan.tags()).to.deep.equal({
+            "someShape.thisIsNull": null,
+            "someShape.thisIsUndefined": undefined,
+        });
+    }
+
+    @test public async testTracingContext_addJsonRPCParameters() {
+        const tracer = new MockTracer();
+        const span = tracer.startSpan('testTracingContext_addJsonRPCParameters');
+        const ctx = { span };
+        TraceContext.addJsonRPCParameters(ctx, {
+            one: "one",
+            two: {
+                name: "two",
+                some: "shape",
+                containing: "PII",
+            },
+            three: "three",
+        });
+
+        const mockSpan = tracer.report().spans[0];
+        expect(mockSpan.tags()).to.deep.equal({
+            "rpc.jsonrpc.parameters.one": "one",
+            "rpc.jsonrpc.parameters.two.containing": "PII",
+            "rpc.jsonrpc.parameters.two.name": "two",
+            "rpc.jsonrpc.parameters.two.some": "shape",
+            "rpc.jsonrpc.parameters.three": "three",
+            "rpc.system": "jsonrpc",
+        });
+    }
+
+}
+module.exports = new TestTracing()

package/src/util/tracing.ts

@@ -6,40 +6,157 @@
 
 
 import * as opentracing from 'opentracing';
-import { TracingConfig, initTracerFromEnv, Sampler, SamplingDecision } from 'jaeger-client';
-import { initGlobalTracer } from 'opentracing';
+import { TracingConfig, initTracerFromEnv } from 'jaeger-client';
+import { Sampler, SamplingDecision } from './jaeger-client-types';
+import { followsFrom, initGlobalTracer } from 'opentracing';
 import { injectable } from 'inversify';
+import { ResponseError } from 'vscode-jsonrpc';
+import { log, LogContext } from './logging';
 
 export interface TraceContext {
     span?: opentracing.Span
 }
+export type TraceContextWithSpan = TraceContext & {
+    span: opentracing.Span
+}
+
 
 export namespace TraceContext {
-    export function startSpan(operation: string, ctx: TraceContext): opentracing.Span {
-        const options: opentracing.SpanOptions = {
-            childOf: ctx.span
+    export function startSpan(operation: string, parentCtx?: TraceContext, ...referencedSpans: (opentracing.Span | undefined)[]): opentracing.Span {
+        const options: opentracing.SpanOptions = {};
+        if (parentCtx) {
+            options.childOf = parentCtx.span;
+        }
+        if (referencedSpans) {
+            // note: allthough followsForm's type says it takes 'opentracing.Span | opentracing.SpanContext', it only works with SpanContext (typing mismatch)
+            options.references = referencedSpans.filter(s => s !== undefined).map(s => followsFrom(s!.context()));
         }
+
         return opentracing.globalTracer().startSpan(operation, options);
     }
 
-    export function startAsyncSpan(operation: string, ctx: TraceContext): opentracing.Span {
-        const options: opentracing.SpanOptions = {};
-        if (!!ctx.span) {
-            options.references = [opentracing.followsFrom(ctx.span.context())];
+    export function childContext(operation: string, parentCtx: TraceContext): TraceContextWithSpan {
+        const span = startSpan(operation, parentCtx);
+        return { span };
+    }
+
+    export function setError(ctx: TraceContext, err: Error) {
+        if (!ctx.span) {
+            return;
         }
-        return opentracing.globalTracer().startSpan(operation, options);
+
+        TraceContext.addNestedTags(ctx, {
+            error: {
+                message: err.message,
+                stacktrace: err.stack,
+            },
+        });
+        ctx.span.setTag("error", true);
+    }
+
+    export function setJsonRPCMetadata(ctx: TraceContext, method?: string) {
+        if (!ctx.span) {
+            return;
+        }
+
+        const tags: { [key: string]: any } = {
+            rpc: {
+                system: "jsonrpc",
+                //  version,
+            },
+        };
+        if (method) {
+            tags.rpc.method = method;
+        }
+        addNestedTags(ctx, tags);
+    }
+
+    export function setJsonRPCError(ctx: TraceContext, method: string, err: ResponseError<any>) {
+        if (!ctx.span) {
+            return;
+        }
+        // not use setError bc this is (most likely) a working operation
+
+        setJsonRPCMetadata(ctx);
+        // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/rpc.md#json-rpc
+        addNestedTags(ctx, {
+            rpc: {
+                jsonrpc: {
+                    error_code: err.code,
+                    error_message: err.message,
+                },
+            },
+        });
     }
 
-    export function logError(ctx: TraceContext, err: Error) {
+    export function addJsonRPCParameters(ctx: TraceContext, params: { [key: string]: any }) {
         if (!ctx.span) {
             return;
         }
 
-        ctx.span.log({
-            "error": err.message,
-            "stacktrace": err.stack
-        })
-        ctx.span.setTag("error", true)
+        setJsonRPCMetadata(ctx);
+        addNestedTags(ctx, {
+            rpc: {
+                jsonrpc: {
+                    parameters: params,
+                },
+            },
+        });
+    }
+
+    /**
+     * Does what one would expect from `span.addTags`: Calls `span.addTag` for all keys in map, recursively for objects.
+     * Example:
+     * ```
+     * TraceContext.addNestedTags(ctx, {
+     *    rpc: {
+     *       system: "jsonrpc",
+     *       jsonrpc: {
+     *          version: "1.0",
+     *          method: "test",
+     *          parameters: ["abc", "def"],
+     *       },
+     *    },
+     * });
+     * ```
+     * gives
+     * rpc.system = "jsonrpc"
+     * rpc.jsonrpc.version = "1.0"
+     * rpc.jsonrpc.method = "test"
+     * rpc.jsonrpc.parameters.0 = "abc"
+     * rpc.jsonrpc.parameters.1 = "def"
+     * @param ctx
+     * @param keyValueMap
+     * @returns
+     */
+    export function addNestedTags(ctx: TraceContext, keyValueMap: { [key: string]: any }, _namespace?: string) {
+        if (!ctx.span) {
+            return;
+        }
+        const namespace = _namespace ? `${_namespace}.` : '';
+
+        try {
+            for (const k of Object.keys(keyValueMap)) {
+                const v = keyValueMap[k];
+                if (v instanceof Object) {
+                    addNestedTags(ctx, v, `${namespace}${k}`);
+                } else {
+                    ctx.span.setTag(`${namespace}${k}`, v);
+                }
+            }
+        } catch (err) {
+            // general resilience against odd shapes/parameters
+            log.error("Tracing.addNestedTags", err, { namespace });
+        }
+    }
+
+    export function setOWI(ctx: TraceContext, owi: LogContext) {
+        if (!ctx.span) {
+            return;
+        }
+        addNestedTags(ctx, {
+            context: owi,
+        });
     }
 }
 
@@ -56,11 +173,16 @@ export class TracingManager {
             reporter: {
                 logSpans: false
             },
-            serviceName
+            serviceName,
         }
         const t = initTracerFromEnv(config, {
-            logger: console
+            logger: console,
+            tags: {
+                'service.build.commit': process.env.GITPOD_BUILD_GIT_COMMIT,
+                'service.build.version': process.env.GITPOD_BUILD_VERSION,
+            }
         });
+
         if (opts) {
             if (opts.perOpSampling) {
                 (t as any)._sampler = new PerOperationSampler((t as any)._sampler, opts.perOpSampling);
@@ -132,3 +254,20 @@ export class PerOperationSampler implements Sampler {
         }
     }
 }
+
+// Augment interfaces with an leading parameter "TraceContext" on every method
+type IsValidArg<T> = T extends object ? keyof T extends never ? false : true : true;
+type AddTraceContext<T> =
+    T extends (a: infer A, b: infer B, c: infer C, d: infer D, e: infer E, f: infer F) => infer R ? (
+        IsValidArg<F> extends true ? (ctx: TraceContextWithSpan, a: A, b: B, c: C, d: D, e: E, f: F) => R :
+        IsValidArg<E> extends true ? (ctx: TraceContextWithSpan, a: A, b: B, c: C, d: D, e: E) => R :
+        IsValidArg<D> extends true ? (ctx: TraceContextWithSpan, a: A, b: B, c: C, d: D) => R :
+        IsValidArg<C> extends true ? (ctx: TraceContextWithSpan, a: A, b: B, c: C) => R :
+        IsValidArg<B> extends true ? (ctx: TraceContextWithSpan, a: A, b: B) => R :
+        IsValidArg<A> extends true ? (ctx: TraceContextWithSpan, a: A) => R :
+        (ctx: TraceContextWithSpan) => Promise<R>
+    ) : never;
+
+export type InterfaceWithTraceContext<T> = {
+    [P in keyof T]: AddTraceContext<T[P]>
+};

package/src/workspace-cluster.ts

@@ -35,6 +35,9 @@ export interface WorkspaceCluster {
 
     // An optional set of constraints that limit who can start workspaces on the cluster
     admissionConstraints?: AdmissionConstraint[];
+
+    // An optional set of admission preferences that guide cluster selection
+    admissionPreferences?: AdmissionPreference[];
 }
 
 export type WorkspaceClusterState = "available" | "cordoned" | "draining";
@@ -52,9 +55,13 @@ export namespace TLSConfig {
 export type WorkspaceClusterWoTLS = Omit<WorkspaceCluster, "tls">;
 export type WorkspaceManagerConnectionInfo = Pick<WorkspaceCluster, "name" | "url" | "tls">;
 
-export type AdmissionConstraint = AdmissionConstraintFeaturePreview | AdmissionConstraintHasRole;
+export type AdmissionConstraint = AdmissionConstraintFeaturePreview | AdmissionConstraintHasRole | AdmissionConstraintHasUserLevel;
 export type AdmissionConstraintFeaturePreview = { type: "has-feature-preview" };
 export type AdmissionConstraintHasRole = { type: "has-permission", permission: PermissionName };
+export type AdmissionConstraintHasUserLevel = { type: "has-user-level", level: string };
+
+export type AdmissionPreference = AdmissionPreferenceUserLevel;
+export type AdmissionPreferenceUserLevel = { type: 'user-level', level: string };
 
 
 export const WorkspaceClusterDB = Symbol("WorkspaceClusterDB");