sailfork / t3code-github / apps/ server/ src/ provider/ ProviderInstanceRegistry.ts

import {
  providerInstanceConfigEnabledFlag,
  ProviderInstanceId,
  type ProviderInstanceConfig,
  type ProviderInstanceConfigMap,
  type ProviderInstanceEnvironment,
  type ProviderDriverKind,
  type ResolvedProviderInstanceEnvironment,
  type SecretReference,
  secretReferencesInSettings,
  type ServerProvider,
  type SettingsSecretSlot,
  withSettingsSecrets,
} from "@t3tools/contracts";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Equal from "effect/Equal";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as PubSub from "effect/PubSub";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";

import * as SecretResolver from "@t3tools/secret-provider-core/server/SecretResolver";

import { buildUnavailableProviderSnapshot } from "./unavailableProviderSnapshot.ts";
import * as ProviderInstanceRegistryMutator from "./ProviderInstanceRegistryMutator.ts";
import type { AnyProviderDriver, ProviderInstance } from "@t3tools/provider-core/server/driver";

export class ProviderInstanceRegistry extends Context.Service<
  ProviderInstanceRegistry,
  {
    readonly getInstance: (
      instanceId: ProviderInstanceId,
    ) => Effect.Effect<ProviderInstance | undefined>;
    readonly listInstances: Effect.Effect<ReadonlyArray<ProviderInstance>>;
    readonly listUnavailable: Effect.Effect<ReadonlyArray<ServerProvider>>;
    /** streamChanges subscribes on consumption; use subscribeChanges before forking to avoid missing the next publish. */
    readonly streamChanges: Stream.Stream<void>;
    readonly subscribeChanges: Effect.Effect<PubSub.Subscription<void>, never, Scope.Scope>;
  }
>()("t3/provider/ProviderInstanceRegistry") {}

interface InstanceSecrets {
  readonly environment: ResolvedProviderInstanceEnvironment;
  readonly config: ReadonlyArray<SettingsSecretSlot & { readonly value: string }>;
}

interface LiveEntry {
  readonly instance: ProviderInstance;
  readonly scope: Scope.Closeable;
  readonly entry: ProviderInstanceConfig;
  readonly secrets: InstanceSecrets;
}

interface RegistryState {
  readonly entries: Ref.Ref<ReadonlyMap<ProviderInstanceId, LiveEntry>>;
  readonly unavailable: Ref.Ref<ReadonlyMap<ProviderInstanceId, ServerProvider>>;
  // Configs parked on an unreadable secret. A settings save that leaves one alone does not read
  // its vault again, so a locked vault is not prompted for on every unrelated save.
  readonly secretsUnreadable: Ref.Ref<ReadonlyMap<ProviderInstanceId, ProviderInstanceConfig>>;
  readonly changes: PubSub.PubSub<void>;
}

const entryEqual = (a: ProviderInstanceConfig, b: ProviderInstanceConfig): boolean =>
  Equal.equals(a, b);

const secretReferencesIn = (environment: ProviderInstanceEnvironment): Array<SecretReference> =>
  environment.flatMap((variable) => (typeof variable.value === "string" ? [] : [variable.value]));

const configSecretReferences = <R>(
  driver: AnyProviderDriver<R> | undefined,
  entry: ProviderInstanceConfig,
) => (driver === undefined ? [] : secretReferencesInSettings(driver.configSchema, entry.config));

const secretReferencesOf = <R>(
  driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>,
  entry: ProviderInstanceConfig,
): ReadonlyArray<SecretReference> => [
  ...secretReferencesIn(entry.environment ?? []),
  ...configSecretReferences(driversById.get(entry.driver), entry).map(({ reference }) => reference),
];

const withoutSecretReferences = (
  environment: ProviderInstanceEnvironment,
): ResolvedProviderInstanceEnvironment =>
  environment.flatMap((variable) =>
    typeof variable.value === "string" ? [{ ...variable, value: variable.value }] : [],
  );

const readInstanceSecrets = Effect.fn("ProviderInstanceRegistry.readInstanceSecrets")(function* <R>(
  driver: AnyProviderDriver<R> | undefined,
  entry: ProviderInstanceConfig,
) {
  const variables = entry.environment ?? [];
  const configFields = configSecretReferences(driver, entry);
  const references = [
    ...secretReferencesIn(variables),
    ...configFields.map(({ reference }) => reference),
  ];
  const values =
    references.length === 0 ? [] : yield* (yield* SecretResolver.SecretResolver).read(references);
  const unreadable: Array<string> = [];
  let index = 0;
  // An empty secret reads as unreadable, so a driver cannot fall back to an inherited credential.
  const next = () => {
    const secret = values[index++];
    return secret === undefined || secret.trim() === "" ? undefined : secret;
  };
  const environment: ResolvedProviderInstanceEnvironment = variables.flatMap((variable) => {
    if (typeof variable.value === "string") return [{ ...variable, value: variable.value }];
    const secret = next();
    if (secret === undefined) {
      unreadable.push(variable.name);
      return [];
    }
    return [{ ...variable, value: secret, sensitive: true }];
  });
  const config = configFields.flatMap(({ field, key }) => {
    const secret = next();
    if (secret !== undefined) return [{ field, key, value: secret }];
    unreadable.push(field);
    return [];
  });
  const secrets: InstanceSecrets = { environment, config };
  return { secrets, unreadable };
});

/** Conflicting saved flags must preserve any explicit disable. */
const resolveEntryEnabled = (entry: ProviderInstanceConfig, typedConfig: unknown): boolean => {
  const rawConfigEnabled = providerInstanceConfigEnabledFlag(entry.config);
  if (entry.enabled === false || rawConfigEnabled === false) {
    return false;
  }
  return entry.enabled ?? providerInstanceConfigEnabledFlag(typedConfig) ?? true;
};

type BlockedReason = (driver: ProviderDriverKind) => string | undefined;

// The enabled state `buildEntry` decodes, so a disabled instance never reads its secrets.
const isEntryEnabled = Effect.fn("ProviderInstanceRegistry.isEntryEnabled")(function* <R>(
  driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>,
  entry: ProviderInstanceConfig,
) {
  const driver = driversById.get(entry.driver);
  if (!driver) return false;
  const decoder = Schema.decodeUnknownEffect(driver.configSchema);
  const decoded = yield* decoder(entry.config ?? driver.defaultConfig()).pipe(Effect.option);
  return Option.isSome(decoded) && resolveEntryEnabled(entry, decoded.value);
});

const buildEntry = Effect.fn("ProviderInstanceRegistry.buildEntry")(function* <R>(input: {
  readonly driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>;
  readonly blockedReason: BlockedReason;
  readonly parentScope: Scope.Scope;
  readonly instanceId: ProviderInstanceId;
  readonly rawInstanceId: string;
  readonly entry: ProviderInstanceConfig;
  readonly deferSecrets: boolean;
}): Effect.fn.Return<
  | { readonly kind: "live"; readonly live: LiveEntry }
  | {
      readonly kind: "unavailable";
      readonly snapshot: ServerProvider;
      readonly secretsUnreadable?: true;
    },
  never,
  R | SecretResolver.SecretResolver
> {
  const { driversById, parentScope, instanceId, rawInstanceId, entry, deferSecrets } = input;
  const blocked = input.blockedReason(entry.driver);
  if (blocked !== undefined) {
    return {
      kind: "unavailable" as const,
      snapshot: yield* buildUnavailableProviderSnapshot({
        driverKind: entry.driver,
        instanceId,
        displayName: entry.displayName,
        accentColor: entry.accentColor,
        reason: blocked,
      }),
    };
  }
  const driver = driversById.get(entry.driver);
  if (!driver) {
    return {
      kind: "unavailable" as const,
      snapshot: yield* buildUnavailableProviderSnapshot({
        driverKind: entry.driver,
        instanceId,
        displayName: entry.displayName,
        accentColor: entry.accentColor,
        reason: `Driver '${entry.driver}' is not registered in this build.`,
      }),
    };
  }

  const decoder = Schema.decodeUnknownEffect(driver.configSchema);
  const decodeResult = yield* decoder(entry.config ?? driver.defaultConfig()).pipe(Effect.result);
  if (decodeResult._tag === "Failure") {
    const issue = decodeResult.failure;
    const detail = issue.message ?? String(issue);
    yield* Effect.logError("Failed to decode provider instance config", {
      instanceId: rawInstanceId,
      driver: entry.driver,
      detail,
    });
    return {
      kind: "unavailable" as const,
      snapshot: yield* buildUnavailableProviderSnapshot({
        driverKind: entry.driver,
        instanceId,
        displayName: entry.displayName,
        accentColor: entry.accentColor,
        reason: `Invalid config for instance '${rawInstanceId}': ${detail}`,
      }),
    };
  }

  const typedConfig = decodeResult.success;
  const enabled = resolveEntryEnabled(entry, typedConfig);
  if (deferSecrets && enabled && secretReferencesOf(driversById, entry).length > 0) {
    return {
      kind: "unavailable" as const,
      snapshot: yield* buildUnavailableProviderSnapshot({
        driverKind: entry.driver,
        instanceId,
        displayName: entry.displayName,
        accentColor: entry.accentColor,
        reason: "Reading secrets…",
      }),
    };
  }
  const { secrets, unreadable } = enabled
    ? yield* readInstanceSecrets(driver, entry)
    : {
        secrets: { environment: withoutSecretReferences(entry.environment ?? []), config: [] },
        unreadable: [],
      };
  // Starting with a blank credential would fail later with a less useful error, or fall back to
  // whatever the server inherited.
  if (unreadable.length > 0) {
    return {
      kind: "unavailable" as const,
      secretsUnreadable: true as const,
      snapshot: yield* buildUnavailableProviderSnapshot({
        driverKind: entry.driver,
        instanceId,
        displayName: entry.displayName,
        accentColor: entry.accentColor,
        reason: `Could not read ${unreadable.join(", ")} from its secret provider. Unlock it, then refresh.`,
      }),
    };
  }

  const childScope = yield* Scope.fork(parentScope);

  const createResult = yield* driver
    .create({
      instanceId,
      displayName: entry.displayName,
      accentColor: entry.accentColor,
      environment: secrets.environment,
      enabled,
      config:
        secrets.config.length === 0
          ? typedConfig
          : withSettingsSecrets(typedConfig, secrets.config),
    })
    .pipe(Effect.provideService(Scope.Scope, childScope), Effect.result);
  if (createResult._tag === "Failure") {
    yield* Effect.logError("Failed to create provider instance", {
      instanceId: rawInstanceId,
      driver: entry.driver,
      detail: createResult.failure.detail,
    });
    yield* Scope.close(childScope, Exit.void).pipe(Effect.ignore);
    return {
      kind: "unavailable" as const,
      snapshot: yield* buildUnavailableProviderSnapshot({
        driverKind: entry.driver,
        instanceId,
        displayName: entry.displayName,
        accentColor: entry.accentColor,
        reason: `Driver '${entry.driver}' failed to create instance: ${createResult.failure.detail}`,
      }),
    };
  }

  return {
    kind: "live" as const,
    live: {
      instance: createResult.success,
      scope: childScope,
      entry,
      secrets,
    },
  };
});

const makeReconcile = <R>(input: {
  readonly state: RegistryState;
  readonly driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>;
  readonly blockedReason: BlockedReason;
  readonly parentScope: Scope.Scope;
}): ((
  configMap: ProviderInstanceConfigMap,
  rebuild?: ReadonlySet<ProviderInstanceId>,
  deferSecrets?: boolean,
) => Effect.Effect<void, never, R | SecretResolver.SecretResolver>) => {
  const { state, driversById, blockedReason, parentScope } = input;
  return (configMap, rebuild = new Set(), deferSecrets = false) =>
    Effect.gen(function* () {
      const previousEntries = yield* Ref.get(state.entries);
      const previousUnavailable = yield* Ref.get(state.unavailable);
      const previousSecretsUnreadable = yield* Ref.get(state.secretsUnreadable);
      const nextRaw = Object.entries(configMap);
      const nextKeys = new Set<ProviderInstanceId>(
        nextRaw.map(([raw]) => ProviderInstanceId.make(raw)),
      );

      // Close changed/removed scopes before replacements to preserve one live scope per id.
      const removedIds: Array<ProviderInstanceId> = [];
      const replacedIds = new Set<ProviderInstanceId>();
      for (const [instanceId, live] of previousEntries) {
        if (!nextKeys.has(instanceId)) {
          removedIds.push(instanceId);
          continue;
        }
        const nextEntry = configMap[instanceId];
        if (
          rebuild.has(instanceId) ||
          (nextEntry !== undefined && !entryEqual(live.entry, nextEntry))
        ) {
          replacedIds.add(instanceId);
        }
      }
      const retiredIds = [...removedIds, ...replacedIds];
      if (retiredIds.length > 0) {
        const remaining = new Map(previousEntries);
        for (const id of retiredIds) remaining.delete(id);
        yield* Ref.set(state.entries, remaining);
      }
      for (const id of retiredIds) {
        const live = previousEntries.get(id);
        if (live) {
          yield* Scope.close(live.scope, Exit.void).pipe(Effect.ignore);
        }
      }

      const parkedSnapshot = (instanceId: ProviderInstanceId, entry: ProviderInstanceConfig) => {
        const parked = previousSecretsUnreadable.get(instanceId);
        return !rebuild.has(instanceId) && parked !== undefined && entryEqual(parked, entry)
          ? previousUnavailable.get(instanceId)
          : undefined;
      };

      // Read every secret the builds below need in one go, so a vault unlocks once.
      const references = yield* Effect.forEach(nextRaw, ([rawInstanceId, entry]) =>
        Effect.gen(function* () {
          const instanceId = ProviderInstanceId.make(rawInstanceId);
          const kept = previousEntries.has(instanceId) && !replacedIds.has(instanceId);
          return kept ||
            parkedSnapshot(instanceId, entry) !== undefined ||
            !(yield* isEntryEnabled(driversById, entry))
            ? []
            : secretReferencesOf(driversById, entry);
        }),
      ).pipe(Effect.map((perEntry) => perEntry.flat()));
      if (references.length > 0 && !deferSecrets) {
        yield* (yield* SecretResolver.SecretResolver).read(references);
      }

      const builtEntries = new Map<ProviderInstanceId, LiveEntry>();
      const builtUnavailable = new Map<ProviderInstanceId, ServerProvider>();
      const builtSecretsUnreadable = new Map<ProviderInstanceId, ProviderInstanceConfig>();
      let orderChanged = false;
      const previousOrder = [...previousEntries.keys()];
      const nextOrder: Array<ProviderInstanceId> = [];

      for (const [rawInstanceId, entry] of nextRaw) {
        const instanceId = ProviderInstanceId.make(rawInstanceId);
        nextOrder.push(instanceId);

        const existing = previousEntries.get(instanceId);
        if (existing !== undefined && !replacedIds.has(instanceId)) {
          builtEntries.set(instanceId, existing);
          continue;
        }
        const parked = parkedSnapshot(instanceId, entry);
        if (parked !== undefined) {
          builtUnavailable.set(instanceId, parked);
          builtSecretsUnreadable.set(instanceId, entry);
          continue;
        }

        const result = yield* buildEntry({
          driversById,
          blockedReason,
          parentScope,
          instanceId,
          rawInstanceId,
          entry,
          deferSecrets,
        });
        if (result.kind === "live") {
          builtEntries.set(instanceId, result.live);
        } else {
          builtUnavailable.set(instanceId, result.snapshot);
          if (result.secretsUnreadable) builtSecretsUnreadable.set(instanceId, entry);
        }
      }

      if (previousOrder.length === nextOrder.length) {
        for (let i = 0; i < previousOrder.length; i++) {
          if (previousOrder[i] !== nextOrder[i]) {
            orderChanged = true;
            break;
          }
        }
      } else {
        orderChanged = true;
      }

      const entriesChanged =
        orderChanged ||
        removedIds.length > 0 ||
        replacedIds.size > 0 ||
        builtEntries.size !== previousEntries.size;
      const unavailableChanged =
        builtUnavailable.size !== previousUnavailable.size ||
        [...builtUnavailable].some(([id, snapshot]) => {
          const prev = previousUnavailable.get(id);
          return prev === undefined || !Equal.equals(prev, snapshot);
        }) ||
        [...previousUnavailable].some(([id]) => !builtUnavailable.has(id));

      yield* Ref.set(state.entries, builtEntries);
      yield* Ref.set(state.unavailable, builtUnavailable);
      yield* Ref.set(state.secretsUnreadable, builtSecretsUnreadable);

      if (entriesChanged || unavailableChanged) {
        yield* PubSub.publish(state.changes, undefined);
      }
    });
};

export const makeProviderInstanceRegistry = Effect.fn(
  "ProviderInstanceRegistry.makeProviderInstanceRegistry",
)(function* <R>(input: {
  readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
  readonly configMap: ProviderInstanceConfigMap;
  /** A reason to show instead of running a driver, such as an administrator's policy. */
  readonly blockedReason?: BlockedReason | undefined;
}): Effect.fn.Return<
  {
    readonly registry: ProviderInstanceRegistry["Service"];
    readonly mutator: ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutatorShape;
  },
  never,
  R | SecretResolver.SecretResolver | Scope.Scope
> {
  const driversById = new Map<ProviderDriverKind, AnyProviderDriver<R>>(
    input.drivers.map((driver) => [driver.driverKind, driver]),
  );

  // Capture the enclosing scope so per-instance child scopes can be
  // attached to it at `reconcile` time. Without this, `reconcile`
  // called later (e.g. from the hydration layer) would attach child
  // scopes to the *caller's* scope instead of the registry's.
  const parentScope = yield* Scope.Scope;

  const driverContext = yield* Effect.context<R | SecretResolver.SecretResolver>();

  const entries = yield* Ref.make<ReadonlyMap<ProviderInstanceId, LiveEntry>>(new Map());
  const unavailable = yield* Ref.make<ReadonlyMap<ProviderInstanceId, ServerProvider>>(new Map());
  const secretsUnreadable = yield* Ref.make<
    ReadonlyMap<ProviderInstanceId, ProviderInstanceConfig>
  >(new Map());
  const changes = yield* PubSub.unbounded<void>();
  yield* Effect.addFinalizer(() => PubSub.shutdown(changes));

  const state: RegistryState = { entries, unavailable, secretsUnreadable, changes };
  const reconcileWithR = makeReconcile({
    state,
    driversById,
    blockedReason: input.blockedReason ?? (() => undefined),
    parentScope,
  });
  const configMapRef = yield* Ref.make(input.configMap);
  const semaphore = yield* Semaphore.make(1);
  const reconcile: ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutatorShape["reconcile"] =
    (configMap) =>
      semaphore.withPermits(1)(
        Ref.set(configMapRef, configMap).pipe(
          Effect.andThen(reconcileWithR(configMap)),
          Effect.provideContext(driverContext),
        ),
      );

  // Rebuilds an instance only when it was unavailable or its secrets changed, so a refresh does
  // not restart providers whose credentials are the same.
  const reloadSecrets: ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutatorShape["reloadSecrets"] =
    Effect.fn("ProviderInstanceRegistry.reloadSecrets")(
      function* (instanceId) {
        const configMap = yield* Ref.get(configMapRef);
        const targets = yield* Effect.filter(Object.entries(configMap), ([rawInstanceId, entry]) =>
          (instanceId === undefined || rawInstanceId === instanceId) &&
          secretReferencesOf(driversById, entry).length > 0
            ? isEntryEnabled(driversById, entry)
            : Effect.succeed(false),
        );
        if (targets.length === 0) return;
        const resolver = yield* SecretResolver.SecretResolver;
        const references = targets.flatMap(([, entry]) => secretReferencesOf(driversById, entry));
        yield* resolver.invalidate(references);
        yield* resolver.read(references);
        const live = yield* Ref.get(entries);
        const rebuild = new Set<ProviderInstanceId>();
        for (const [rawInstanceId, entry] of targets) {
          const current = live.get(ProviderInstanceId.make(rawInstanceId));
          if (current === undefined) {
            rebuild.add(ProviderInstanceId.make(rawInstanceId));
            continue;
          }
          const { secrets, unreadable } = yield* readInstanceSecrets(
            driversById.get(entry.driver),
            entry,
          );
          // A failed re-read keeps the working instance and the value it already holds.
          if (unreadable.length === 0 && !Equal.equals(secrets, current.secrets)) {
            rebuild.add(current.instance.instanceId);
          }
        }
        yield* reconcileWithR(configMap, rebuild);
      },
      (effect) => semaphore.withPermits(1)(effect),
      Effect.provideContext(driverContext),
    );

  // Reading secrets can wait on a vault unlock, so the server does not wait for it to start.
  yield* semaphore.withPermits(1)(
    Ref.set(configMapRef, input.configMap).pipe(
      Effect.andThen(reconcileWithR(input.configMap, new Set(), true)),
      Effect.provideContext(driverContext),
    ),
  );
  const startupReferences = yield* Effect.filter(Object.entries(input.configMap), ([, entry]) =>
    secretReferencesOf(driversById, entry).length > 0
      ? isEntryEnabled(driversById, entry)
      : Effect.succeed(false),
  ).pipe(
    Effect.map((targets) => targets.flatMap(([, entry]) => secretReferencesOf(driversById, entry))),
  );
  if (startupReferences.length > 0) {
    // The read waits outside the lock so other mutations are not held for a vault prompt; a
    // configuration saved meanwhile has already reconciled itself.
    yield* Effect.gen(function* () {
      yield* (yield* SecretResolver.SecretResolver).read(startupReferences);
      yield* semaphore.withPermits(1)(
        Effect.gen(function* () {
          const current = yield* Ref.get(configMapRef);
          if (current === input.configMap) yield* reconcileWithR(current);
        }),
      );
    }).pipe(Effect.provideContext(driverContext), Effect.forkScoped);
  }

  const registry: ProviderInstanceRegistry["Service"] = {
    getInstance: (id) => Ref.get(entries).pipe(Effect.map((map) => map.get(id)?.instance)),
    listInstances: Ref.get(entries).pipe(
      Effect.map(
        (map) =>
          Array.from(map.values(), (live) => live.instance) as ReadonlyArray<ProviderInstance>,
      ),
    ),
    listUnavailable: Ref.get(unavailable).pipe(
      Effect.map((map) => Array.from(map.values()) as ReadonlyArray<ServerProvider>),
    ),
    get streamChanges() {
      return Stream.fromPubSub(changes);
    },
    get subscribeChanges() {
      return PubSub.subscribe(changes);
    },
  };

  const mutator: ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutatorShape = {
    reconcile,
    reloadSecrets,
  };

  return { registry, mutator };
});

export const layer = <R>(input: {
  readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
  readonly configMap: ProviderInstanceConfigMap;
  readonly blockedReason?: BlockedReason | undefined;
}): Layer.Layer<
  ProviderInstanceRegistry | ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutator,
  never,
  R | SecretResolver.SecretResolver
> =>
  Layer.effectContext(
    makeProviderInstanceRegistry(input).pipe(
      Effect.map(({ registry, mutator }) =>
        Context.make(ProviderInstanceRegistry, registry).pipe(
          Context.add(ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutator, mutator),
        ),
      ),
    ),
  ) as Layer.Layer<
    ProviderInstanceRegistry | ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutator,
    never,
    R | SecretResolver.SecretResolver
  >;