@pagopa/dx-savemoney 0.3.2 → 0.4.0

package/src/azure/pricing/__tests__/pricing-service.test.ts

@@ -0,0 +1,315 @@
+/**
+ * Tests for the PricingService façade — covers memoization and error
+ * swallowing. The underlying resolvers are exercised in their own tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { FetchLike } from "../client.js";
+import type { PricingResponse } from "../schema.js";
+
+import { DiskCache } from "../cache.js";
+import { PricingClient } from "../client.js";
+import { PricingService } from "../pricing-service.js";
+import { makeTestCacheDir, removeTestCacheDir } from "../test-cache-dir.js";
+
+function makeFetch(body: PricingResponse): {
+  fetch: FetchLike;
+  spy: ReturnType<typeof vi.fn>;
+} {
+  const spy = vi.fn<FetchLike>().mockResolvedValue({
+    json: async () => body,
+    ok: true,
+    status: 200,
+    statusText: "OK",
+  });
+  return { fetch: spy, spy };
+}
+
+let dir: string;
+
+beforeEach(async () => {
+  dir = await makeTestCacheDir("pricing-service");
+});
+
+afterEach(async () => {
+  await removeTestCacheDir(dir);
+});
+
+describe("PricingService", () => {
+  it("memoizes identical VM lookups within the same instance", async () => {
+    const body: PricingResponse = {
+      Items: [
+        {
+          armRegionName: "westeurope",
+          armSkuName: "Standard_B2s",
+          currencyCode: "EUR",
+          productName: "Virtual Machines BS Series",
+          retailPrice: 0.05,
+          skuName: "B2s",
+          type: "Consumption",
+          unitOfMeasure: "1 Hour",
+          unitPrice: 0.05,
+        },
+      ],
+      NextPageLink: null,
+    };
+    const { fetch, spy } = makeFetch(body);
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch,
+    });
+    const service = new PricingService(client);
+
+    const [a, b] = await Promise.all([
+      service.resolveVm({
+        armRegionName: "westeurope",
+        armSkuName: "Standard_B2s",
+      }),
+      service.resolveVm({
+        armRegionName: "westeurope",
+        armSkuName: "Standard_B2s",
+      }),
+    ]);
+
+    expect(a).toEqual(b);
+    // Only one underlying fetch despite two concurrent calls.
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns undefined and does not throw when the resolver errors", async () => {
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch: vi.fn<FetchLike>().mockRejectedValue(new Error("boom")),
+    });
+    const service = new PricingService(client);
+
+    const result = await service.resolveVm({
+      armRegionName: "westeurope",
+      armSkuName: "Standard_B2s",
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("scopes the in-memory memo by os hint", async () => {
+    const body: PricingResponse = {
+      Items: [
+        {
+          armRegionName: "westeurope",
+          armSkuName: "Standard_B2s",
+          currencyCode: "EUR",
+          productName: "Virtual Machines BS Series",
+          retailPrice: 0.05,
+          skuName: "B2s",
+          type: "Consumption",
+          unitOfMeasure: "1 Hour",
+          unitPrice: 0.05,
+        },
+        {
+          armRegionName: "westeurope",
+          armSkuName: "Standard_B2s",
+          currencyCode: "EUR",
+          productName: "Virtual Machines BS Series Windows",
+          retailPrice: 0.09,
+          skuName: "B2s",
+          type: "Consumption",
+          unitOfMeasure: "1 Hour",
+          unitPrice: 0.09,
+        },
+      ],
+      NextPageLink: null,
+    };
+    const { fetch, spy } = makeFetch(body);
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch,
+    });
+    const service = new PricingService(client);
+
+    const linux = await service.resolveVm({
+      armRegionName: "westeurope",
+      armSkuName: "Standard_B2s",
+      os: "linux",
+    });
+    const windows = await service.resolveVm({
+      armRegionName: "westeurope",
+      armSkuName: "Standard_B2s",
+      os: "windows",
+    });
+
+    expect(linux?.amount).toBeLessThan(windows?.amount ?? 0);
+    // Same underlying filter, served from DiskCache — one fetch only.
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("PricingService disk memoization", () => {
+  it("memoizes identical disk lookups within the same instance", async () => {
+    const body: PricingResponse = {
+      Items: [
+        {
+          armRegionName: "westeurope",
+          currencyCode: "EUR",
+          productName: "Premium SSD Managed Disks",
+          retailPrice: 19.71,
+          skuName: "P10 LRS",
+          type: "Consumption",
+          unitOfMeasure: "1/Month",
+          unitPrice: 19.71,
+        },
+      ],
+      NextPageLink: null,
+    };
+    const { fetch, spy } = makeFetch(body);
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch,
+    });
+    const service = new PricingService(client);
+
+    const [a, b] = await Promise.all([
+      service.resolveDisk({
+        armRegionName: "westeurope",
+        diskSizeGiB: 128,
+        sku: "Premium_LRS",
+      }),
+      service.resolveDisk({
+        armRegionName: "westeurope",
+        diskSizeGiB: 128,
+        sku: "Premium_LRS",
+      }),
+    ]);
+
+    expect(a).toEqual(b);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("memoizes disk lookups with display and ARM region names as the same key", async () => {
+    const body: PricingResponse = {
+      Items: [
+        {
+          armRegionName: "westeurope",
+          currencyCode: "EUR",
+          productName: "Premium SSD Managed Disks",
+          retailPrice: 19.71,
+          skuName: "P10 LRS",
+          type: "Consumption",
+          unitOfMeasure: "1/Month",
+          unitPrice: 19.71,
+        },
+      ],
+      NextPageLink: null,
+    };
+    const { fetch, spy } = makeFetch(body);
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch,
+    });
+    const service = new PricingService(client);
+
+    const [a, b] = await Promise.all([
+      service.resolveDisk({
+        armRegionName: "West Europe",
+        diskSizeGiB: 128,
+        sku: "Premium_LRS",
+      }),
+      service.resolveDisk({
+        armRegionName: "westeurope",
+        diskSizeGiB: 128,
+        sku: "Premium_LRS",
+      }),
+    ]);
+
+    expect(a).toEqual(b);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("PricingService App Service Plan memoization", () => {
+  it("memoizes identical App Service Plan lookups within the same instance", async () => {
+    const body: PricingResponse = {
+      Items: [
+        {
+          armRegionName: "westeurope",
+          currencyCode: "EUR",
+          meterName: "S1 App",
+          productName: "Azure App Service Standard Plan - Linux",
+          retailPrice: 0.08337,
+          skuName: "S1",
+          type: "Consumption",
+          unitOfMeasure: "1 Hour",
+          unitPrice: 0.08337,
+        },
+      ],
+      NextPageLink: null,
+    };
+    const { fetch, spy } = makeFetch(body);
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch,
+    });
+    const service = new PricingService(client);
+
+    const [a, b] = await Promise.all([
+      service.resolveAppServicePlan({
+        armRegionName: "westeurope",
+        os: "linux",
+        skuName: "S1",
+        workerCount: 1,
+      }),
+      service.resolveAppServicePlan({
+        armRegionName: "westeurope",
+        os: "linux",
+        skuName: "S1",
+        workerCount: 1,
+      }),
+    ]);
+
+    expect(a).toEqual(b);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("memoizes App Service Plan lookups by canonical region and worker count", async () => {
+    const body: PricingResponse = {
+      Items: [
+        {
+          armRegionName: "westeurope",
+          currencyCode: "EUR",
+          meterName: "S1 App",
+          productName: "Azure App Service Standard Plan - Linux",
+          retailPrice: 0.08337,
+          skuName: "S1",
+          type: "Consumption",
+          unitOfMeasure: "1 Hour",
+          unitPrice: 0.08337,
+        },
+      ],
+      NextPageLink: null,
+    };
+    const { fetch, spy } = makeFetch(body);
+    const client = new PricingClient({
+      cache: new DiskCache({ dir }),
+      fetch,
+    });
+    const service = new PricingService(client);
+
+    const [a, b] = await Promise.all([
+      service.resolveAppServicePlan({
+        armRegionName: "West Europe",
+        os: "linux",
+        skuName: "S1",
+        workerCount: 1.2,
+      }),
+      service.resolveAppServicePlan({
+        armRegionName: "westeurope",
+        os: "linux",
+        skuName: "S1",
+        workerCount: 2,
+      }),
+    ]);
+
+    expect(a).toEqual(b);
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/azure/pricing/cache.ts

@@ -0,0 +1,92 @@
+/**
+ * Disk-backed cache for Azure Retail Prices API responses.
+ *
+ * Retail prices change rarely (Azure publishes a new snapshot at most once
+ * a month) so a long TTL is safe and dramatically cuts cold-start latency
+ * for `dx savemoney`. Each cache entry is a JSON file whose name is the
+ * SHA-256 of the request key (the OData `$filter` string); the entry is
+ * considered fresh while `now - mtime <= ttl`.
+ *
+ * The cache directory is created lazily on first write. Read/write
+ * failures never throw: a corrupted or unreadable entry simply behaves
+ * like a miss so the caller refetches from the API. This matches the
+ * "best-effort cache" semantics expected by HTTP-level caches.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, open, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Defaults documented in the package README. */
+export const DEFAULT_CACHE_DIR = join(
+  process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"),
+  "dx-savemoney",
+  "pricing",
+);
+export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type DiskCacheOptions = {
+  /** Absolute path where cache entries are stored. */
+  dir?: string;
+  /** Maximum age of an entry before it is treated as a miss. */
+  ttlMs?: number;
+};
+
+/**
+ * Best-effort JSON cache. Keys are arbitrary strings; values are anything
+ * serialisable via `JSON.stringify`.
+ */
+export class DiskCache {
+  readonly dir: string;
+  readonly ttlMs: number;
+
+  constructor(options: DiskCacheOptions = {}) {
+    this.dir = options.dir ?? DEFAULT_CACHE_DIR;
+    this.ttlMs = options.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+  }
+
+  /**
+   * Returns the cached value for `key` if present and still fresh.
+   * Returns `undefined` on miss, expiry, or any I/O / parse error.
+   */
+  async get<T>(key: string): Promise<T | undefined> {
+    const path = this.pathFor(key);
+    try {
+      const file = await open(path, "r");
+      try {
+        const stats = await file.stat();
+        if (Date.now() - stats.mtimeMs > this.ttlMs) return undefined;
+        const raw = await file.readFile("utf8");
+        return JSON.parse(raw) as T;
+      } finally {
+        await file.close();
+      }
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Absolute filesystem path used to store `key`. Exposed for tests. */
+  pathFor(key: string): string {
+    const hash = createHash("sha256").update(key).digest("hex");
+    return join(this.dir, `${hash}.json`);
+  }
+
+  /**
+   * Persists `value` under `key`. Silently swallows write errors so a
+   * read-only filesystem cannot break the calling pipeline.
+   */
+  async set<T>(key: string, value: T): Promise<void> {
+    const path = this.pathFor(key);
+    try {
+      await mkdir(this.dir, { mode: 0o700, recursive: true });
+      await writeFile(path, JSON.stringify(value), {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+    } catch {
+      // Best-effort: cache failures must not surface to callers.
+    }
+  }
+}

package/src/azure/pricing/client.ts

@@ -0,0 +1,137 @@
+/**
+ * HTTP client for the Azure Retail Prices REST API.
+ *
+ * Endpoint: https://prices.azure.com/api/retail/prices
+ *
+ * The API is **public and unauthenticated** — no `TokenCredential`
+ * required — but it is rate-limited per source IP. To stay polite we:
+ *   1. Cache the full paginated result for each `$filter` on disk
+ *      (`DiskCache`, 24h TTL by default) and return cached items
+ *      immediately on hit.
+ *   2. Follow `NextPageLink` sequentially (no parallel page fetches).
+ *
+ * The client is constructed with an optional `fetch` implementation to
+ * make it trivially mockable in tests; in production it uses the global
+ * `fetch` available since Node 18.
+ */
+
+import { getLogger } from "@logtape/logtape";
+
+import type { PriceItem, PricingResponse } from "./schema.js";
+
+import { DiskCache } from "./cache.js";
+import { PricingResponseSchema } from "./schema.js";
+
+const DEFAULT_BASE_URL = "https://prices.azure.com/api/retail/prices";
+/** Hard cap on pages to follow — protects against runaway loops. */
+const MAX_PAGES = 100;
+
+export type FetchLike = (
+  input: string,
+  init?: { signal?: AbortSignal },
+) => Promise<{
+  json(): Promise<unknown>;
+  ok: boolean;
+  status: number;
+  statusText: string;
+}>;
+
+export type PricingClientOptions = {
+  /** Override the base URL. Useful for staging or fixtures. */
+  baseUrl?: string;
+  /** Disk cache instance. Defaults to the user's cache directory. */
+  cache?: DiskCache;
+  /**
+   * Currency to ask the API for. The response items always carry their
+   * own `currencyCode`, but specifying it here returns localised prices
+   * where available. Defaults to "EUR".
+   */
+  currencyCode?: string;
+  /** Inject a custom `fetch` (used by tests). Defaults to the global one. */
+  fetch?: FetchLike;
+};
+
+/**
+ * Thin wrapper around the Retail Prices endpoint.
+ *
+ * Use `query(filter)` with an OData `$filter` expression, e.g.:
+ *   serviceName eq 'Virtual Machines' and armRegionName eq 'westeurope' and armSkuName eq 'Standard_B2s'
+ */
+export class PricingClient {
+  private readonly baseUrl: string;
+  private readonly cache: DiskCache;
+  private readonly currencyCode: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly logger = getLogger(["savemoney", "azure", "pricing"]);
+
+  constructor(options: PricingClientOptions = {}) {
+    this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    this.cache = options.cache ?? new DiskCache();
+    this.currencyCode = options.currencyCode ?? "EUR";
+    // The global `fetch` exists in Node ≥ 18 / 24 but TypeScript types it
+    // loosely; we narrow to `FetchLike` to keep the surface intentional.
+    this.fetchImpl =
+      options.fetch ??
+      ((input, init) => fetch(input, init) as ReturnType<FetchLike>);
+  }
+
+  /**
+   * Returns every meter that matches the given OData `$filter`, following
+   * pagination transparently. Results are cached for `cache.ttlMs`.
+   *
+   * Throws when the API returns a non-2xx status or a response that fails
+   * schema validation: pricing lookups are advisory (callers should treat
+   * "no data" as "skip the savings estimate") but a malformed payload
+   * signals a real upstream change that deserves attention.
+   */
+  async query(filter: string): Promise<PriceItem[]> {
+    const cacheKey = `${this.currencyCode}|${filter}`;
+    const cached = await this.cache.get<PriceItem[]>(cacheKey);
+    if (cached) {
+      this.logger.debug(
+        `pricing cache hit (${cached.length} items): ${filter}`,
+      );
+      return cached;
+    }
+
+    const items: PriceItem[] = [];
+    const firstUrl = this.buildUrl(filter);
+    let nextUrl: string | undefined = firstUrl;
+    for (let page = 0; nextUrl && page < MAX_PAGES; page++) {
+      const response: PricingResponse = await this.fetchPage(nextUrl);
+      items.push(...response.Items);
+      nextUrl = response.NextPageLink ?? undefined;
+    }
+    if (nextUrl) {
+      this.logger.warn(
+        `pricing query truncated at ${MAX_PAGES} pages: ${filter}`,
+      );
+    }
+    await this.cache.set(cacheKey, items);
+    return items;
+  }
+
+  private buildUrl(filter: string): string {
+    const params = new URLSearchParams({
+      $filter: filter,
+      "api-version": "2023-01-01-preview",
+      currencyCode: this.currencyCode,
+    });
+    return `${this.baseUrl}?${params.toString()}`;
+  }
+
+  private async fetchPage(url: string): Promise<PricingResponse> {
+    const res = await this.fetchImpl(url);
+    if (!res.ok) {
+      throw new Error(
+        `Azure Retail Prices API returned ${res.status} ${res.statusText}`,
+      );
+    }
+    const body = await res.json().catch((error: unknown) => {
+      throw new Error("Azure Retail Prices API returned invalid JSON", {
+        cause: error,
+      });
+    });
+    return PricingResponseSchema.parse(body);
+  }
+}

package/src/azure/pricing/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal pricing module surface used by the Azure orchestrator.
+ */
+
+export { PricingClient, type PricingClientOptions } from "./client.js";
+export { PricingService } from "./pricing-service.js";

package/src/azure/pricing/pricing-service.ts

@@ -0,0 +1,125 @@
+/**
+ * High-level facade that exposes per-resource pricing resolvers backed by
+ * a shared `PricingClient` (and therefore a shared disk cache).
+ *
+ * Two responsibilities:
+ *  1. Dispatch the right resolver for the right resource kind.
+ *  2. Memoize identical lookups within a single run so concurrent
+ *     analyzers asking for the same `(sku, region, …)` only hit the
+ *     network (or disk cache) once.
+ *  3. Swallow resolver errors and return `undefined` — the savings
+ *     estimate is best-effort and should never break the main analysis
+ *     flow.
+ */
+
+import { getLogger } from "@logtape/logtape";
+
+import type { Money } from "../../finding.js";
+import type { PricingClient } from "./client.js";
+import type {
+  ResolveAppServicePlanInput,
+  ResolveDiskInput,
+  ResolvePublicIpInput,
+  ResolveVmInput,
+} from "./resolvers/index.js";
+
+import {
+  normalizeArmRegion,
+  resolveAppServicePlanMonthlyPrice,
+  resolveDiskMonthlyPrice,
+  resolvePublicIpMonthlyPrice,
+  resolveVmMonthlyPrice,
+} from "./resolvers/index.js";
+
+const logger = getLogger(["savemoney", "azure", "pricing"]);
+
+export class PricingService {
+  /** In-memory memo keyed by the canonicalised lookup input. */
+  private readonly memo = new Map<string, Promise<Money | undefined>>();
+
+  constructor(private readonly client: PricingClient) {}
+
+  /**
+   * Resolves the estimated monthly cost of an App Service Plan SKU.
+   * Returns `undefined` on no-match or on error.
+   */
+  async resolveAppServicePlan(
+    input: ResolveAppServicePlanInput,
+  ): Promise<Money | undefined> {
+    const key = `app-service-plan|${normalizeArmRegion(input.armRegionName)}|${input.skuName}|${input.os ?? "any"}|${Math.ceil(input.workerCount ?? 1)}`;
+    return this.memoize(key, () =>
+      this.safeResolve(() =>
+        resolveAppServicePlanMonthlyPrice(this.client, input),
+      ),
+    );
+  }
+
+  /**
+   * Resolves the estimated monthly cost of a Managed Disk. Returns
+   * `undefined` on no-match (e.g. unsupported SKU like UltraSSD) or on
+   * error.
+   */
+  async resolveDisk(input: ResolveDiskInput): Promise<Money | undefined> {
+    const key = `disk|${normalizeArmRegion(input.armRegionName)}|${input.sku}|${input.diskSizeGiB}`;
+    return this.memoize(key, () =>
+      this.safeResolve(() => resolveDiskMonthlyPrice(this.client, input)),
+    );
+  }
+
+  /**
+   * Resolves the estimated monthly cost of a Public IP. Returns
+   * `undefined` on no-match or on error.
+   */
+  async resolvePublicIp(
+    input: ResolvePublicIpInput,
+  ): Promise<Money | undefined> {
+    const key = `public-ip|${normalizeArmRegion(input.armRegionName)}|${input.sku}|${input.allocation}`;
+    return this.memoize(key, () =>
+      this.safeResolve(() => resolvePublicIpMonthlyPrice(this.client, input)),
+    );
+  }
+
+  /**
+   * Resolves the estimated monthly cost of a Virtual Machine SKU.
+   * Returns `undefined` on no-match or on error.
+   */
+  async resolveVm(input: ResolveVmInput): Promise<Money | undefined> {
+    const key = `vm|${normalizeArmRegion(input.armRegionName)}|${input.armSkuName}|${input.os ?? "linux"}`;
+    return this.memoize(key, () =>
+      this.safeResolve(() => resolveVmMonthlyPrice(this.client, input)),
+    );
+  }
+
+  private memoize(
+    key: string,
+    factory: () => Promise<Money | undefined>,
+  ): Promise<Money | undefined> {
+    const cached = this.memo.get(key);
+    if (cached) return cached;
+    const promise = factory().then((money) => {
+      if (money === undefined) {
+        // Debug-level so it shows up under `-v` but doesn't clutter the
+        // default output. Helps diagnosing "I see no savings" reports
+        // when the Retail Prices API has no entry for the queried
+        // (region, sku, …) combination.
+        logger.debug(`Pricing lookup returned no match for ${key}`);
+      }
+      return money;
+    });
+    this.memo.set(key, promise);
+    return promise;
+  }
+
+  private async safeResolve(
+    factory: () => Promise<Money | undefined>,
+  ): Promise<Money | undefined> {
+    try {
+      return await factory();
+    } catch (error) {
+      logger.warn(
+        `Pricing lookup failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return undefined;
+    }
+  }
+}