@barekey/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,422 @@
+import {
+  BillingUnavailableError,
+  FsNotAvailableError,
+  NetworkError,
+  VariableNotFoundError,
+} from "./errors.js";
+import { BarekeyEnvHandle } from "./handle.js";
+import {
+  evaluateDefinition,
+  inferSelectedArmFromDecision,
+  parseDeclaredValue,
+  validateDynamicOptions,
+} from "./internal/evaluate.js";
+import { getJson, postJson } from "./internal/http.js";
+import { validateRequirements } from "./internal/requirements.js";
+import { resolveRuntimeContext, type BarekeyRuntimeContext } from "./internal/runtime.js";
+import { MemoryCache } from "./internal/cache.js";
+import { DEFAULT_TYPEGEN_TTL_MS, resolveTtlMilliseconds } from "./internal/ttl.js";
+import {
+  resolveInstalledSdkGeneratedTypesPath,
+  type TypegenManifest,
+  writeInstalledSdkGeneratedTypes,
+} from "./internal/typegen.js";
+import type {
+  BarekeyClientOptions,
+  BarekeyEvaluatedValue,
+  BarekeyGeneratedTypeMap,
+  BarekeyGetOptions,
+  BarekeyJsonConfig,
+  BarekeyKnownKey,
+  BarekeyTypegenResult,
+  BarekeyVariableDefinition,
+} from "./types.js";
+
+type DefinitionsResponse = {
+  definitions: Array<BarekeyVariableDefinition>;
+};
+
+type EvaluateResponse = {
+  name: string;
+  kind: BarekeyEvaluatedValue["kind"];
+  declaredType: BarekeyEvaluatedValue["declaredType"];
+  value: string;
+  decision?: BarekeyEvaluatedValue["decision"];
+};
+
+type SharedTypegenWatcher = {
+  intervalMs: number;
+  inFlight: Promise<void> | null;
+  warned: boolean;
+  timer: ReturnType<typeof setInterval>;
+};
+
+const sharedTypegenWatchers = new Map<string, SharedTypegenWatcher>();
+
+function createDefaultFetch(): typeof globalThis.fetch {
+  if (typeof globalThis.fetch === "function") {
+    return globalThis.fetch.bind(globalThis);
+  }
+
+  return (async () => {
+    throw new NetworkError({
+      message: "fetch is not available in this runtime.",
+    });
+  }) as typeof globalThis.fetch;
+}
+
+function createTypegenInterval(callback: () => void, intervalMs: number): ReturnType<typeof setInterval> {
+  const timer = setInterval(callback, intervalMs);
+  if ("unref" in timer && typeof timer.unref === "function") {
+    timer.unref();
+  }
+  return timer;
+}
+
+function warnAutomaticTypegenFailure(error: unknown): void {
+  const message =
+    error instanceof Error ? error.message : "Barekey automatic typegen refresh failed.";
+  console.warn(`[barekey] Automatic typegen refresh failed.\n${message}`);
+}
+
+export class BarekeyClient {
+  private readonly options: BarekeyClientOptions;
+  private readonly fetchFn: typeof globalThis.fetch;
+  private readonly definitionCache = new MemoryCache<BarekeyVariableDefinition>();
+  private readonly evaluationCache = new MemoryCache<BarekeyEvaluatedValue>();
+  private runtimeContextPromise: Promise<BarekeyRuntimeContext> | null = null;
+  private requirementsPromise: Promise<void> | null = null;
+  private typegenWatcherStarted = false;
+
+  constructor();
+  constructor(options: {
+    organization: string;
+    project: string;
+    environment: string;
+    requirements?: BarekeyClientOptions["requirements"];
+    typegen?: BarekeyClientOptions["typegen"];
+  });
+  constructor(options: {
+    json: BarekeyJsonConfig;
+    requirements?: BarekeyClientOptions["requirements"];
+    typegen?: BarekeyClientOptions["typegen"];
+  });
+  constructor(options: BarekeyClientOptions = {}) {
+    this.options = options;
+    this.fetchFn = createDefaultFetch();
+  }
+
+  get<TKey extends BarekeyKnownKey>(
+    name: TKey,
+    options?: BarekeyGetOptions,
+  ): BarekeyEnvHandle<BarekeyGeneratedTypeMap[TKey]>;
+  get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<unknown>;
+  get(name: string, options?: BarekeyGetOptions): BarekeyEnvHandle<unknown> {
+    return new BarekeyEnvHandle(
+      async () => await this.resolveEvaluatedValue(name, options),
+    );
+  }
+
+  async typegen(): Promise<BarekeyTypegenResult> {
+    const context = await this.getRuntimeContext();
+    const generatedTypesPath = await resolveInstalledSdkGeneratedTypesPath();
+    if (generatedTypesPath === null) {
+      throw new FsNotAvailableError({
+        message: "Barekey could not update generated SDK types because filesystem access is unavailable.",
+      });
+    }
+
+    const manifest = await this.fetchTypegenManifest(context);
+    return await writeInstalledSdkGeneratedTypes(manifest);
+  }
+
+  private async getRuntimeContext(): Promise<BarekeyRuntimeContext> {
+    if (this.runtimeContextPromise === null) {
+      const runtimeContextPromise = resolveRuntimeContext(this.options, this.fetchFn);
+      runtimeContextPromise.catch(() => {
+        if (this.runtimeContextPromise === runtimeContextPromise) {
+          this.runtimeContextPromise = null;
+        }
+      });
+      this.runtimeContextPromise = runtimeContextPromise;
+    }
+    return await this.runtimeContextPromise;
+  }
+
+  private async fetchTypegenManifest(context?: BarekeyRuntimeContext): Promise<TypegenManifest> {
+    const resolvedContext = context ?? (await this.getRuntimeContext());
+    return await getJson<TypegenManifest>({
+      fetchFn: this.fetchFn,
+      baseUrl: resolvedContext.baseUrl,
+      path: `/v1/typegen/manifest?projectSlug=${encodeURIComponent(
+        resolvedContext.project,
+      )}&stageSlug=${encodeURIComponent(resolvedContext.environment)}&orgSlug=${encodeURIComponent(
+        resolvedContext.organization,
+      )}`,
+      auth: resolvedContext.auth,
+    });
+  }
+
+  private getTypegenIntervalMs(): number {
+    const typegenOptions = this.options.typegen;
+    if (typegenOptions === false) {
+      return 0;
+    }
+    if (typegenOptions?.ttl === undefined) {
+      return DEFAULT_TYPEGEN_TTL_MS;
+    }
+    return resolveTtlMilliseconds(typegenOptions.ttl, "typegen.ttl");
+  }
+
+  private async startTypegenWatcher(context: BarekeyRuntimeContext): Promise<void> {
+    if (this.options.typegen === false || context.environment !== "development") {
+      return;
+    }
+
+    const generatedTypesPath = await resolveInstalledSdkGeneratedTypesPath();
+    if (generatedTypesPath === null) {
+      throw new FsNotAvailableError({
+        message: "Automatic Barekey typegen refresh requires filesystem access.",
+      });
+    }
+
+    const intervalMs = this.getTypegenIntervalMs();
+    const watcherKey = [
+      context.baseUrl,
+      context.organization,
+      context.project,
+      context.environment,
+      generatedTypesPath,
+    ].join("|");
+
+    const runWatcher = async (watcher: SharedTypegenWatcher): Promise<void> => {
+      if (watcher.inFlight !== null) {
+        await watcher.inFlight;
+        return;
+      }
+
+      watcher.inFlight = (async () => {
+        try {
+          await this.typegen();
+          watcher.warned = false;
+        } catch (error: unknown) {
+          if (!watcher.warned) {
+            warnAutomaticTypegenFailure(error);
+            watcher.warned = true;
+          }
+        } finally {
+          watcher.inFlight = null;
+        }
+      })();
+
+      await watcher.inFlight;
+    };
+
+    const existingWatcher = sharedTypegenWatchers.get(watcherKey);
+    if (existingWatcher !== undefined) {
+      if (intervalMs < existingWatcher.intervalMs) {
+        clearInterval(existingWatcher.timer);
+        existingWatcher.intervalMs = intervalMs;
+        existingWatcher.timer = createTypegenInterval(() => {
+          void runWatcher(existingWatcher);
+        }, intervalMs);
+      }
+      return;
+    }
+
+    const watcher: SharedTypegenWatcher = {
+      intervalMs,
+      inFlight: null,
+      warned: false,
+      timer: createTypegenInterval(() => {
+        void runWatcher(watcher);
+      }, intervalMs),
+    };
+    sharedTypegenWatchers.set(watcherKey, watcher);
+    void runWatcher(watcher);
+  }
+
+  private ensureTypegenWatcher(context: BarekeyRuntimeContext): void {
+    if (this.typegenWatcherStarted || this.options.typegen === false || context.environment !== "development") {
+      return;
+    }
+
+    this.typegenWatcherStarted = true;
+    void this.startTypegenWatcher(context).catch((error: unknown) => {
+      warnAutomaticTypegenFailure(error);
+    });
+  }
+
+  private buildDefinitionCacheKey(context: BarekeyRuntimeContext, name: string): string {
+    return [context.organization, context.project, context.environment, name].join("|");
+  }
+
+  private buildEvaluationCacheKey(
+    context: BarekeyRuntimeContext,
+    name: string,
+    options?: BarekeyGetOptions,
+  ): string {
+    return [
+      context.organization,
+      context.project,
+      context.environment,
+      name,
+      options?.seed ?? "",
+      options?.key ?? "",
+    ].join("|");
+  }
+
+  private async fetchDefinitions(names?: Array<string>): Promise<Array<BarekeyVariableDefinition>> {
+    const context = await this.getRuntimeContext();
+    const response = await postJson<DefinitionsResponse>({
+      fetchFn: this.fetchFn,
+      baseUrl: context.baseUrl,
+      path: "/v1/env/definitions",
+      payload: {
+        orgSlug: context.organization,
+        projectSlug: context.project,
+        stageSlug: context.environment,
+        ...(names === undefined ? {} : { names }),
+      },
+      auth: context.auth,
+    });
+
+    for (const definition of response.definitions) {
+      this.definitionCache.set(this.buildDefinitionCacheKey(context, definition.name), definition);
+    }
+
+    return response.definitions;
+  }
+
+  private async ensureRequirementsValidated(): Promise<void> {
+    const context = await this.getRuntimeContext();
+    const requirements = context.requirements;
+    if (requirements === undefined) {
+      return;
+    }
+
+    if (this.requirementsPromise === null) {
+      const requirementsPromise = (async () => {
+        const definitions = await this.fetchDefinitions();
+        const values: Record<string, unknown> = {};
+        for (const definition of definitions) {
+          const evaluated = await evaluateDefinition(definition);
+          values[definition.name] = parseDeclaredValue(evaluated.value, evaluated.declaredType);
+        }
+        await validateRequirements(requirements, values);
+      })();
+      requirementsPromise.catch(() => {
+        if (this.requirementsPromise === requirementsPromise) {
+          this.requirementsPromise = null;
+        }
+      });
+      this.requirementsPromise = requirementsPromise;
+    }
+
+    await this.requirementsPromise;
+  }
+
+  private async getStaticDefinition(name: string): Promise<BarekeyVariableDefinition> {
+    await this.ensureRequirementsValidated();
+    const context = await this.getRuntimeContext();
+    const cacheKey = this.buildDefinitionCacheKey(context, name);
+    const cached = this.definitionCache.get(cacheKey);
+    if (cached !== null) {
+      return cached;
+    }
+
+    const definitions = await this.fetchDefinitions([name]);
+    const resolved = definitions[0];
+    if (resolved === undefined) {
+      throw new VariableNotFoundError();
+    }
+    return resolved;
+  }
+
+  private async resolveStaticValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    const definition = await this.getStaticDefinition(name);
+    return await evaluateDefinition(definition, options);
+  }
+
+  private async resolveDynamicValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    await this.ensureRequirementsValidated();
+    const context = await this.getRuntimeContext();
+    const cacheKey = this.buildEvaluationCacheKey(context, name, options);
+    const dynamic = options?.dynamic;
+    const dynamicTtlMs =
+      dynamic !== undefined && dynamic !== true
+        ? resolveTtlMilliseconds(dynamic.ttl, "dynamic.ttl")
+        : null;
+    if (dynamic !== true) {
+      const cached = this.evaluationCache.getRecord(cacheKey);
+      if (cached !== null && dynamicTtlMs !== null && Date.now() - cached.storedAtMs <= dynamicTtlMs) {
+        return cached.value;
+      }
+    }
+
+    let resolved: BarekeyEvaluatedValue;
+    try {
+      const evaluated = await postJson<EvaluateResponse>({
+        fetchFn: this.fetchFn,
+        baseUrl: context.baseUrl,
+        path: "/v1/env/evaluate",
+        payload: {
+          orgSlug: context.organization,
+          projectSlug: context.project,
+          stageSlug: context.environment,
+          name,
+          seed: options?.seed,
+          key: options?.key,
+        },
+        auth: context.auth,
+      });
+
+      resolved = {
+        name: evaluated.name,
+        kind: evaluated.kind,
+        declaredType: evaluated.declaredType,
+        value: evaluated.value,
+        decision: evaluated.decision,
+        selectedArm: inferSelectedArmFromDecision(evaluated.decision),
+      };
+    } catch (error: unknown) {
+      if (!(error instanceof BillingUnavailableError)) {
+        throw error;
+      }
+
+      const freshDefinitions = await this.fetchDefinitions([name]);
+      const freshDefinition = freshDefinitions[0];
+      if (freshDefinition === undefined) {
+        throw new VariableNotFoundError();
+      }
+      resolved = await evaluateDefinition(freshDefinition, options);
+    }
+
+    if (dynamicTtlMs !== null) {
+      // dynamic.ttl is evaluated per read, so keep the cached fetch time and let
+      // later calls decide whether the entry is still fresh for their requested ttl.
+      this.evaluationCache.set(cacheKey, resolved);
+    }
+
+    return resolved;
+  }
+
+  private async resolveEvaluatedValue(
+    name: string,
+    options?: BarekeyGetOptions,
+  ): Promise<BarekeyEvaluatedValue> {
+    const context = await this.getRuntimeContext();
+    this.ensureTypegenWatcher(context);
+    validateDynamicOptions(options);
+    if (options?.dynamic === undefined) {
+      return await this.resolveStaticValue(name, options);
+    }
+    return await this.resolveDynamicValue(name, options);
+  }
+}