@bjorntech/alchemy-azure 0.2.0-beta.57

package/src/Credentials.ts

@@ -0,0 +1,69 @@
+import { ClientSecretCredential, DefaultAzureCredential } from "@azure/identity";
+import type { TokenCredential } from "@azure/identity";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { getAuthProvider } from "alchemy/Auth/AuthProvider";
+import { ALCHEMY_PROFILE, AlchemyProfile } from "alchemy/Auth/Profile";
+import {
+  AZURE_AUTH_PROVIDER_NAME,
+  type AzureAuthConfig,
+  type AzureResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export interface AzureCredentialsService {
+  subscriptionId: string;
+  tenantId?: string;
+  clientId?: string;
+  clientSecret?: Redacted.Redacted<string>;
+  credential: TokenCredential;
+}
+
+export class AzureCredentials extends Context.Service<AzureCredentials, AzureCredentialsService>()(
+  "Azure.Credentials",
+) {}
+
+export const fromAuthProvider = () =>
+  Layer.effect(
+    AzureCredentials,
+    Effect.gen(function* () {
+      const profile = yield* AlchemyProfile;
+      const auth = yield* getAuthProvider<AzureAuthConfig, AzureResolvedCredentials>(
+        AZURE_AUTH_PROVIDER_NAME,
+      );
+      const profileName = yield* ALCHEMY_PROFILE;
+      const ci = yield* Config.boolean("CI").pipe(Config.withDefault(false));
+
+      const resolved = yield* profile
+        .loadOrConfigure<AzureAuthConfig>(auth, profileName, { ci })
+        .pipe(Effect.flatMap((config) => auth.read(profileName, config)));
+
+      return createAzureCredentials(resolved);
+    }),
+  );
+
+export function createAzureCredentials(
+  credentials: AzureResolvedCredentials,
+): AzureCredentialsService {
+  if (credentials.method === "servicePrincipal") {
+    return {
+      subscriptionId: credentials.subscriptionId,
+      tenantId: credentials.tenantId,
+      clientId: credentials.clientId,
+      clientSecret: credentials.clientSecret,
+      credential: new ClientSecretCredential(
+        credentials.tenantId,
+        credentials.clientId,
+        Redacted.value(credentials.clientSecret),
+      ),
+    };
+  }
+
+  return {
+    subscriptionId: credentials.subscriptionId,
+    tenantId: credentials.tenantId,
+    credential: new DefaultAzureCredential(),
+  };
+}

package/src/Errors.ts

@@ -0,0 +1,101 @@
+import * as Schema from "effect/Schema";
+
+/**
+ * Tagged error raised by Azure provider lifecycle methods when an Azure
+ * SDK call fails. Use `Effect.catchTag("AzureError", ...)` to handle
+ * these with full type-safety.
+ */
+export class AzureError extends Schema.TaggedErrorClass<AzureError>()(
+  "AzureError",
+  {
+    message: Schema.String,
+    /** Logical operation that triggered the failure, e.g. `reconcile resource group`. */
+    operation: Schema.optional(Schema.String),
+    /** Physical name of the Azure resource the operation targeted. */
+    resource: Schema.optional(Schema.String),
+    /** HTTP status code, when the underlying error carries one. */
+    statusCode: Schema.optional(Schema.Number),
+    /** Azure error code, e.g. `ResourceAlreadyExists`. */
+    code: Schema.optional(Schema.String),
+    cause: Schema.optional(Schema.Defect({ includeStack: true })),
+  },
+) {}
+
+/**
+ * Shape Azure SDK errors typically expose. Used to extract `statusCode`
+ * and `code` for {@link AzureError} construction.
+ */
+interface AzureSdkError extends Error {
+  statusCode?: number;
+  code?: string;
+}
+
+const hasSdkShape = (error: unknown): error is AzureSdkError =>
+  error instanceof Error &&
+  (("statusCode" in error && typeof (error as AzureSdkError).statusCode === "number") ||
+    ("code" in error && typeof (error as AzureSdkError).code === "string"));
+
+/**
+ * Walk an error's `cause` chain to find the underlying Azure SDK error.
+ *
+ * `Effect.tryPromise(thunk)` (the single-argument form used across the
+ * providers) wraps a rejected promise in an `UnknownError`, stashing the real
+ * SDK error — including its `statusCode` / `code` — under `cause`. Detection
+ * helpers must therefore look past the top-level error, or idempotent `read` /
+ * `delete` paths never recognise a 404 / 409.
+ */
+function findSdkError(error: unknown): AzureSdkError | undefined {
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    if (hasSdkShape(current)) return current;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+export function isAzureError(error: unknown): error is AzureSdkError {
+  return findSdkError(error) !== undefined;
+}
+
+export function isNotFound(error: unknown): boolean {
+  if (error instanceof AzureError && error.statusCode === 404) return true;
+  return findSdkError(error)?.statusCode === 404;
+}
+
+export function isAlreadyExists(error: unknown): boolean {
+  const matches = (statusCode?: number, code?: string, message?: string) =>
+    statusCode === 409 || code === "ResourceAlreadyExists" || !!message?.includes("already exists");
+  if (error instanceof AzureError && matches(error.statusCode, error.code, error.message)) {
+    return true;
+  }
+  const sdk = findSdkError(error);
+  return matches(sdk?.statusCode, sdk?.code, sdk?.message);
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Wrap an arbitrary thrown value as an {@link AzureError}, preserving
+ * `statusCode` / `code` from Azure SDK errors. Suitable as the `catch:`
+ * mapper for `Effect.tryPromise`.
+ */
+export function azureError(input: {
+  operation: string;
+  resource?: string;
+  cause: unknown;
+}): AzureError {
+  const { operation, resource, cause } = input;
+  const sdk = findSdkError(cause);
+  return new AzureError({
+    message: `Failed to ${operation}${resource ? ` "${resource}"` : ""}: ${errorMessage(cause)}`,
+    operation,
+    resource,
+    statusCode: sdk?.statusCode,
+    code: sdk?.code,
+    cause,
+  });
+}

package/src/Internal.ts

@@ -0,0 +1,184 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Redacted from "effect/Redacted";
+import { Stack, Stage } from "alchemy";
+import type { ResourceGroup } from "./ResourceGroup.ts";
+
+/**
+ * Emit a periodic "sign of life" heartbeat to stderr while a long-running effect
+ * is in flight, so operators are not left staring at a silent console during slow
+ * Azure provisioning (Container App environments, Cosmos DB, SQL, VMs, etc.).
+ *
+ * Nothing is logged when the wrapped effect settles before the first interval, so
+ * fast paths and the in-memory test mock stay quiet. Apply this selectively to the
+ * genuinely slow resources only — do not blanket-wrap every Azure call.
+ *
+ * @example
+ * ```ts
+ * yield* Effect.tryPromise({ try, catch }).pipe(
+ *   withHeartbeat(`Container Apps managed environment "${name}"`),
+ * );
+ * ```
+ */
+export const withHeartbeat =
+  (label: string, interval: Duration.Input = Duration.seconds(60)) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.gen(function* () {
+      const start = Date.now();
+      const tick = Effect.sync(() => {
+        const seconds = Math.round((Date.now() - start) / 1000);
+        console.error(`[azure] still working on ${label} (${seconds}s elapsed)…`);
+      }).pipe(Effect.delay(interval), Effect.forever);
+      // Fork the heartbeat loop as a child fiber and guarantee it is interrupted as
+      // soon as the operation settles (success, failure, or interruption), so no
+      // timer leaks and the console goes quiet the moment work completes.
+      const fiber = yield* tick.pipe(Effect.forkChild);
+      return yield* self.pipe(Effect.ensuring(Fiber.interrupt(fiber)));
+    });
+
+export type NamedResourceGroup = string | ResourceGroup;
+
+export interface PhysicalNameOptions {
+  maxLength?: number;
+  suffixLength?: number;
+  lowercase?: boolean;
+  delimiter?: string;
+  sanitize?: (name: string) => string;
+}
+
+export const makePhysicalNames = Effect.gen(function* () {
+  const stack = yield* Stack;
+  const stage = yield* Stage;
+
+  const defaultName = (
+    id: string,
+    instanceId: string,
+    options: PhysicalNameOptions = {},
+  ) => {
+    const suffixLength = options.suffixLength ?? 16;
+    const delimiter = options.delimiter ?? "-";
+    const lowercase = options.lowercase ?? false;
+    const prefix = `${stack.name}${delimiter}${id}${delimiter}${stage}${delimiter}`;
+    const suffix = base32(Buffer.from(instanceId, "hex")).slice(0, suffixLength);
+    const raw = `${prefix}${suffix}`;
+    const maxLength = options.maxLength ?? 64;
+    const truncated = maxLength && raw.length > maxLength
+      ? `${prefix.slice(0, maxLength - suffix.length)}${suffix}`
+      : raw;
+    const sanitized = (lowercase ? truncated.toLowerCase() : truncated).replaceAll(
+      lowercase ? /[^a-z0-9-]/g : /[^a-zA-Z0-9-]/g,
+      delimiter,
+    );
+    return options.sanitize?.(sanitized) ?? sanitized;
+  };
+
+  const physicalName = (
+    id: string,
+    instanceId: string,
+    name: string | undefined,
+    options?: PhysicalNameOptions,
+  ) => name ?? defaultName(id, instanceId, options);
+
+  return { defaultName, physicalName };
+});
+
+export const physicalName = (
+  id: string,
+  instanceId: string,
+  name: string | undefined,
+  options?: PhysicalNameOptions,
+) => makePhysicalNames.pipe(Effect.map((names) => names.physicalName(id, instanceId, name, options)));
+
+function base32(bytes: Uint8Array): string {
+  const alphabet = "abcdefghijklmnopqrstuvwxyz234567";
+  const outputLength = Math.ceil((bytes.length * 8) / 5);
+  const output = Array.from<string>({ length: outputLength });
+  let buffer = 0;
+  let bits = 0;
+  let index = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output[index++] = alphabet[(buffer >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    output[index++] = alphabet[(buffer << (5 - bits)) & 31];
+  }
+  return index === outputLength ? output.join("") : output.slice(0, index).join("");
+}
+
+export const resourceGroupName = (resourceGroup: NamedResourceGroup) =>
+  Effect.gen(function* () {
+    if (resourceGroup === undefined) return undefined as never;
+    if (typeof resourceGroup === "string") return resourceGroup;
+    return yield* resolveResourceValue(resourceGroup.name);
+  });
+
+export const resourceGroupLocation = (resourceGroup: NamedResourceGroup) =>
+  Effect.gen(function* () {
+    if (typeof resourceGroup === "string") return undefined;
+    return yield* resolveResourceValue(resourceGroup.location);
+  });
+
+export function resolveResourceValue<T>(value: T) {
+  return Effect.gen(function* () {
+    if (Effect.isEffect(value)) return yield* value;
+    const maybeOutput = value as { asEffect?: () => Effect.Effect<Effect.Effect<T>> };
+    if (typeof maybeOutput?.asEffect === "function") {
+      const accessor = yield* maybeOutput.asEffect();
+      return yield* accessor;
+    }
+    return value;
+  });
+}
+
+export const requireLocation = (
+  id: string,
+  location: string | undefined,
+  resourceGroup: NamedResourceGroup,
+) =>
+  Effect.gen(function* () {
+    const resolved = location ?? (yield* resourceGroupLocation(resourceGroup));
+    if (!resolved) {
+      throw new Error(`${id} requires location when resourceGroup is a string.`);
+    }
+    return resolved;
+  });
+
+export async function collectAzurePages<T>(source: AsyncIterable<T> | Promise<{ value?: T[] }> | Promise<T[]>): Promise<T[]> {
+  const resolved = await source;
+  if (isAsyncIterable<T>(resolved)) {
+    const items: T[] = [];
+    for await (const item of resolved) items.push(item);
+    return items;
+  }
+  return Array.isArray(resolved) ? resolved : (resolved.value ?? []);
+}
+
+export function diffValueEqual(left: unknown, right: unknown) {
+  return JSON.stringify(stableDiffValue(left)) === JSON.stringify(stableDiffValue(right));
+}
+
+function stableDiffValue(value: unknown): unknown {
+  if (Redacted.isRedacted(value)) return Redacted.value(value);
+  if (Array.isArray(value)) return value.map(stableDiffValue);
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => [key, stableDiffValue(record[key])]),
+    );
+  }
+  return value;
+}
+
+function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
+  return typeof (value as { [Symbol.asyncIterator]?: unknown })?.[Symbol.asyncIterator] === "function";
+}