@lukoweb/apitogo 0.2.2 → 0.2.12

package/dist/declarations/cli/platform/client/platform-api.d.ts

@@ -318,6 +318,105 @@ export interface PageFileDto {
     isFile: boolean;
     order: number;
 }
+export interface GatewaySpecUploadDto {
+    specId: string;
+    sha256: string;
+    openApiVersion: string;
+    operationCount: number;
+    added: number;
+    updated: number;
+    removed: number;
+    unchanged: boolean;
+}
+export interface GatewayConfigAcceptedDto {
+    reconciliationId: string;
+    desiredHash: string;
+    state: string;
+    unchanged: boolean;
+}
+export interface GatewayReconciliationDto {
+    id: string;
+    kind: string;
+    state: "Pending" | "Running" | "Succeeded" | "Failed" | "Superseded";
+    desiredHash?: string | null;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    createdAtUtc: string;
+    startedAtUtc?: string | null;
+    finishedAtUtc?: string | null;
+}
+export interface GatewayControlStatusDto {
+    provider: string;
+    tier: string;
+    status: string;
+    baseUrl: string;
+    desiredHash?: string | null;
+    observedHash?: string | null;
+    inSync: boolean;
+    origin?: {
+        mode: string;
+        url?: string | null;
+        health: string;
+        lastProbeAtUtc?: string | null;
+        latencyMs?: number | null;
+        lastErrorCode?: string | null;
+        healthChangedAtUtc?: string | null;
+    } | null;
+    operationCount: number;
+    specSha256?: string | null;
+    cors?: {
+        origin: string;
+        source: string;
+        applied: boolean;
+    }[] | null;
+    openApiPath?: string | null;
+    openApiHash?: string | null;
+    exportAccess?: string | null;
+    latestReconciliation?: GatewayReconciliationDto | null;
+}
+export interface GatewayCapabilitiesResponse {
+    provider: string;
+    tier: string;
+    capabilities: Record<string, boolean>;
+}
+export interface GatewayCheckResultDto {
+    ok: boolean;
+    tier: string;
+    issues: {
+        code: string;
+        field: string;
+        message: string;
+        hint: string;
+    }[];
+    specOperationCount?: number | null;
+}
+export interface GatewayDryRunDto {
+    ok: boolean;
+    issues: {
+        code: string;
+        field: string;
+        message: string;
+        hint: string;
+    }[];
+    changes?: {
+        wouldCreate: boolean;
+        inSync: boolean;
+        operationsAdded: string[];
+        operationsRemoved: string[];
+        nowPublic: string[];
+        nowProtected: string[];
+        nowDenied: string[];
+        originChanged: boolean;
+        policyChanges: string[];
+        hasChanges: boolean;
+    } | null;
+    activeKeys: number;
+    comparedWithGateway: boolean;
+}
+export interface GatewayTeardownAcceptedDto {
+    reconciliationId: string;
+    state: string;
+}
 export interface ProjectSecretDto {
     name: string;
     updatedAtUtc: string;
@@ -407,6 +506,21 @@ export declare class PlatformApiClient {
     setCustomDomain(projectId: string, body: SetUserCustomDomainRequest): Promise<UserCustomDomainResponse>;
     deleteCustomDomain(projectId: string): Promise<void>;
     updateBackendOpenApi(projectId: string, openApiPath: string): Promise<BackendDeploymentDetailDto>;
+    putGatewaySpec(projectId: string, content: string | Uint8Array): Promise<GatewaySpecUploadDto>;
+    putGatewayConfig(projectId: string, body: unknown): Promise<GatewayConfigAcceptedDto>;
+    getGatewayReconciliation(projectId: string, reconciliationId: string): Promise<GatewayReconciliationDto>;
+    getGatewayStatus(projectId: string): Promise<GatewayControlStatusDto>;
+    getGatewayOpenApi(projectId: string): Promise<string>;
+    getGatewayCapabilities(projectId: string): Promise<GatewayCapabilitiesResponse>;
+    checkGateway(projectId: string, body: {
+        config: unknown;
+        spec?: string;
+    }): Promise<GatewayCheckResultDto>;
+    planGateway(projectId: string, body: {
+        config: unknown;
+        spec?: string;
+    }): Promise<GatewayDryRunDto>;
+    deleteGateway(projectId: string): Promise<GatewayTeardownAcceptedDto>;
     getDevPortalBackend(projectId: string): Promise<DevPortalBackendDto | null>;
     getDevPortalSetupStatus(projectId: string): Promise<DevPortalSetupStatusDto>;
     getDevPortalSettings(projectId: string): Promise<DevPortalSettingsDto | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.2",
+  "version": "0.2.12",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/gateway-reference.ts

@@ -0,0 +1,220 @@
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import type { ResolvedGateway } from "./resolve.js";
+
+/** What the gateway checks, in the terms the exported OpenAPI file uses. */
+export type ReferenceOptions = {
+  /** The address callers use. Replaces every server of the spec. */
+  gatewayBaseUrl: string;
+  /** The customer's own API address. It must never appear in the result. */
+  originUrl?: string;
+  jwtRequired: boolean;
+  oidcMetadataUrl?: string;
+  apiKeyRequired: boolean;
+  apiKeyHeader: string;
+  /** Action keys such as `get:/orders`. */
+  publicOperations: ReadonlySet<string>;
+  deniedOperations: ReadonlySet<string>;
+};
+
+/** Header of the API key when the gateway does not say otherwise (same as the platform's OpenAPI export). */
+export const DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
+
+const METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+] as const;
+
+type Json = Record<string, unknown>;
+
+const isObject = (value: unknown): value is Json =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** `GET /orders/` becomes `get:/orders`, the key the platform uses for an operation. */
+export function actionKey(method: string, path: string): string {
+  const trimmed = path.trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const normalized =
+    withSlash.length > 1 ? withSlash.replace(/\/+$/, "") || "/" : withSlash;
+  return `${method.trim().toLowerCase()}:${normalized}`;
+}
+
+/** A config entry like `GET /orders` as an action key, or undefined when it has no method and path. */
+export function configActionKey(entry: string): string | undefined {
+  const match = /^\s*([A-Za-z]+)\s+(\S+)\s*$/.exec(entry);
+  return match?.[1] && match[2] ? actionKey(match[1], match[2]) : undefined;
+}
+
+/**
+ * What the platform's OpenAPI export is made with, from the config: a token is checked when `access.jwt` is on (the
+ * default when `auth` is set), a key unless `access.apiKey` is off.
+ */
+export function referenceOptions(
+  gateway: ResolvedGateway,
+  gatewayBaseUrl: string,
+  keyHeaderName?: string,
+): ReferenceOptions {
+  const access = gateway.policies.access;
+  const jwt = access?.jwt ?? gateway.auth !== undefined;
+  const keys = (list?: string[]) =>
+    new Set(
+      (list ?? []).flatMap((entry) => {
+        const key = configActionKey(entry);
+        return key ? [key] : [];
+      }),
+    );
+  return {
+    gatewayBaseUrl,
+    originUrl: gateway.origin.url,
+    jwtRequired: jwt && gateway.auth !== undefined,
+    oidcMetadataUrl: jwt ? gateway.auth?.metadataUrl : undefined,
+    apiKeyRequired: access?.apiKey ?? true,
+    apiKeyHeader: keyHeaderName ?? access?.apiKeyHeader ?? DEFAULT_KEY_HEADER,
+    publicOperations: keys(gateway.policies.operations?.public),
+    deniedOperations: keys(gateway.policies.operations?.deny),
+  };
+}
+
+export class ReferenceSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReferenceSpecError";
+  }
+}
+
+function operationsOf(paths: Json): [string, Json, (typeof METHODS)[number]][] {
+  return Object.entries(paths).flatMap(([path, item]) =>
+    isObject(item)
+      ? METHODS.filter((method) => isObject(item[method])).map(
+          (method) =>
+            [path, item, method] as [string, Json, (typeof METHODS)[number]],
+        )
+      : [],
+  );
+}
+
+/**
+ * The document the portal's API page shows. It follows what the platform exports for outside docs tools: servers
+ * point at the gateway, the security schemes say what the gateway really checks, denied operations are gone, public
+ * operations carry no security, and the origin address never shows (it is replaced by the gateway address).
+ */
+export function buildReferenceSpec(
+  specText: string,
+  options: ReferenceOptions,
+): Json {
+  let root: unknown;
+  try {
+    root = parse(specText);
+  } catch {
+    throw new ReferenceSpecError("The OpenAPI file could not be read.");
+  }
+  if (!isObject(root) || typeof root.openapi !== "string")
+    throw new ReferenceSpecError("The OpenAPI file could not be read.");
+
+  const doc = structuredClone(root);
+  const paths = isObject(doc.paths) ? doc.paths : {};
+
+  // Denied operations are removed; a path with nothing left goes too.
+  for (const [path, item, method] of operationsOf(paths))
+    if (options.deniedOperations.has(actionKey(method, path)))
+      delete item[method];
+  for (const [path, item] of Object.entries(paths))
+    if (!isObject(item) || !METHODS.some((method) => method in item))
+      delete paths[path];
+
+  // Public operations need neither token nor key.
+  for (const [path, item, method] of operationsOf(paths))
+    if (options.publicOperations.has(actionKey(method, path)))
+      (item[method] as Json).security = [];
+
+  // Servers on paths and operations would point somewhere else, often at the origin.
+  doc.servers = [{ url: options.gatewayBaseUrl.replace(/\/+$/, "") }];
+  for (const item of Object.values(paths)) {
+    if (!isObject(item)) continue;
+    delete item.servers;
+    for (const method of METHODS) {
+      const operation = item[method];
+      if (isObject(operation)) delete operation.servers;
+    }
+  }
+
+  // The document describes the gateway, not the origin: the origin's own schemes are replaced.
+  const schemes: Json = {};
+  const requirement: Json = {};
+  if (options.jwtRequired) {
+    schemes.bearerAuth = {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+    };
+    requirement.bearerAuth = [];
+  }
+  if (options.oidcMetadataUrl)
+    schemes.openIdAuth = {
+      type: "openIdConnect",
+      openIdConnectUrl: options.oidcMetadataUrl,
+    };
+  if (options.apiKeyRequired) {
+    schemes.apiKeyAuth = {
+      type: "apiKey",
+      in: "header",
+      name: options.apiKeyHeader,
+    };
+    requirement.apiKeyAuth = [];
+  }
+  const components = isObject(doc.components) ? doc.components : {};
+  if (Object.keys(schemes).length > 0) components.securitySchemes = schemes;
+  else delete components.securitySchemes;
+  if (Object.keys(components).length > 0) doc.components = components;
+  else delete doc.components;
+  // One requirement with both schemes means both are needed together.
+  doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
+  for (const [, item, method] of operationsOf(paths)) {
+    const operation = item[method] as Json;
+    if (Array.isArray(operation.security) && operation.security.length > 0)
+      delete operation.security;
+  }
+
+  return JSON.parse(hideOrigin(JSON.stringify(doc), options)) as Json;
+}
+
+/** The origin address must not show anywhere, not even in a description. */
+function hideOrigin(text: string, options: ReferenceOptions): string {
+  const origin = options.originUrl?.trim().replace(/\/+$/, "");
+  if (!origin) return text;
+  const gateway = options.gatewayBaseUrl.trim().replace(/\/+$/, "");
+  // JSON.stringify leaves slashes as they are, so the plain address is what to look for.
+  const pattern = new RegExp(
+    origin.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&"),
+    "gi",
+  );
+  return text.replace(pattern, () => gateway);
+}
+
+/** Reads the gateway's OpenAPI file and builds the reference document. Returns JSON text, one key order per input. */
+export async function renderReferenceSpec(
+  gateway: ResolvedGateway,
+  gatewayBaseUrl: string,
+  keyHeaderName?: string,
+): Promise<string> {
+  const file = gateway.specs[0];
+  if (!file)
+    throw new ReferenceSpecError("gateway.specs lists no OpenAPI file.");
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch {
+    throw new ReferenceSpecError(`Cannot read the OpenAPI file ${file}.`);
+  }
+  const spec = buildReferenceSpec(
+    text,
+    referenceOptions(gateway, gatewayBaseUrl, keyHeaderName),
+  );
+  return `${JSON.stringify(spec, null, 2)}\n`;
+}

package/src/config/v2/gateway-request.ts

@@ -0,0 +1,123 @@
+import type { ResolvedGateway } from "./resolve.js";
+
+/**
+ * The body of `PUT /gateway/config`: the wanted state of the gateway (Gateway design doc, 8.9 and 8.12).
+ * Only names of secrets are in it, never values.
+ */
+export type GatewayConfigBody = {
+  provider: string;
+  origin: {
+    mode: "managed" | "proxy";
+    url?: string;
+    healthPath?: string;
+    timeoutSeconds?: number;
+    auth?: { type: string; name?: string; value?: string };
+  };
+  auth?: {
+    mode: string;
+    metadataUrl?: string;
+    issuers?: string[];
+    audiences?: string[];
+  };
+  export?: { access?: string };
+  /** Sites of this project that call the gateway from a browser. The platform adds them to the allowed origins. */
+  corsDerived?: DerivedCorsSite[];
+  policies?: {
+    access?: {
+      jwt?: boolean;
+      apiKey?: boolean;
+      apiKeyHeader?: string;
+      bindKeyToToken?: boolean;
+    };
+    rateLimit?: { calls: number; periodSeconds: number; scope?: string };
+    quota?: { calls: number; periodDays: number; scope?: string };
+    cors?: string[];
+    operations?: { public?: string[]; deny?: string[] };
+  };
+};
+
+export type DerivedCorsSite = { origin: string; source: "portal" | "docs" };
+
+/**
+ * The browser origins of this project's own sites: the portal (from `services.json`) and an external docs site
+ * (from the config). Only the origin is kept, never a path. Sorted, so the same sites always give the same body.
+ */
+export function derivedCorsSites(sites: {
+  portalUrl?: string;
+  docsUrl?: string;
+}): DerivedCorsSite[] {
+  const originOf = (url?: string) => {
+    if (!url) return undefined;
+    try {
+      const { protocol, origin } = new URL(url);
+      return protocol === "https:" ? origin : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+  const found = [
+    { origin: originOf(sites.docsUrl), source: "docs" as const },
+    { origin: originOf(sites.portalUrl), source: "portal" as const },
+  ].flatMap((site) => (site.origin ? [{ ...site, origin: site.origin }] : []));
+  const seen = new Set<string>();
+  return found
+    .filter((site) => !seen.has(site.origin) && seen.add(site.origin))
+    .sort((a, b) => (a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0));
+}
+
+const defined = <T extends Record<string, unknown>>(value: T): T =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== undefined),
+  ) as T;
+
+/**
+ * Turns the resolved `gateway` section into the request body. The spec files are not part of it: they are uploaded
+ * with `PUT /gateway/spec`. Fields the platform fills with defaults are left out when the config does not set them,
+ * so the same config always gives the same body (and the same hash).
+ */
+export function gatewayConfigBody(
+  gateway: ResolvedGateway,
+  derivedCors: DerivedCorsSite[] = [],
+): GatewayConfigBody {
+  const { origin, auth, policies } = gateway;
+  const body: GatewayConfigBody = {
+    provider: gateway.provider,
+    origin: defined({
+      mode: origin.mode,
+      url: origin.url,
+      healthPath: origin.healthPath,
+      timeoutSeconds: origin.timeoutSeconds,
+      auth: origin.auth ? defined({ ...origin.auth }) : undefined,
+    }),
+  };
+  if (auth) body.auth = defined({ ...auth });
+  if (gateway.export) body.export = defined({ ...gateway.export });
+  if (derivedCors.length > 0) body.corsDerived = derivedCors;
+  if (Object.keys(policies).length > 0) {
+    body.policies = defined({
+      access: policies.access ? defined({ ...policies.access }) : undefined,
+      rateLimit: policies.rateLimit
+        ? defined({ ...policies.rateLimit })
+        : undefined,
+      quota: policies.quota ? defined({ ...policies.quota }) : undefined,
+      cors: policies.cors,
+      operations: policies.operations
+        ? defined({ ...policies.operations })
+        : undefined,
+    });
+  }
+  return body;
+}
+
+/** Stable JSON text of a value: object keys sorted, so equal content gives equal text. */
+export function stableJson(value: unknown): string {
+  return JSON.stringify(value, (_key, item) =>
+    item && typeof item === "object" && !Array.isArray(item)
+      ? Object.fromEntries(
+          Object.entries(item as Record<string, unknown>).sort(([a], [b]) =>
+            a < b ? -1 : a > b ? 1 : 0,
+          ),
+        )
+      : item,
+  );
+}

package/src/config/v2/index.ts

@@ -54,15 +54,32 @@ export {
   missingManifestServices,
   parseManifest,
   readManifest,
+  removeServicesFromManifest,
   requiredServices,
   SUPPORTED_MANIFEST_SCHEMA,
   type ServiceManifest,
   serviceReady,
   stubManifest,
+  withGatewayEntry,
   withPortalEntry,
   writeManifest,
 } from "./manifest.js";
 export { MANIFEST_FILE, manifestPathFor } from "./paths.js";
+export {
+  buildReferenceSpec,
+  DEFAULT_KEY_HEADER,
+  type ReferenceOptions,
+  ReferenceSpecError,
+  referenceOptions,
+  renderReferenceSpec,
+} from "./gateway-reference.js";
+export {
+  type DerivedCorsSite,
+  derivedCorsSites,
+  type GatewayConfigBody,
+  gatewayConfigBody,
+  stableJson,
+} from "./gateway-request.js";
 export {
   consoleLinks,
   planPortal,
@@ -84,6 +101,7 @@ export {
   planAddService,
   planRemoveService,
   SERVICES,
+  clearProjectId,
   ServiceEditError,
   setProjectId,
   type ServiceEdit,
@@ -91,6 +109,7 @@ export {
 } from "./services.js";
 export { checkDependencies } from "./rules.js";
 export {
+  clearServices,
   emptyLedger,
   type Ledger,
   LEDGER_VERSION,

package/src/config/v2/ledger.ts

@@ -217,3 +217,19 @@ export async function runPipeline(
   }
   return outcomes;
 }
+
+/** Forgets the recorded steps of services that no longer exist on the platform. Other services keep their entries. */
+export async function clearServices(
+  state: Pick<StatePaths, "file">,
+  services: readonly string[],
+): Promise<void> {
+  const ledger = await readLedger(state);
+  const remaining = Object.fromEntries(
+    Object.entries(ledger.services).filter(
+      ([name]) => !services.includes(name),
+    ),
+  );
+  if (Object.keys(remaining).length === Object.keys(ledger.services).length)
+    return;
+  await writeLedger(state, { ...ledger, services: remaining });
+}

package/src/config/v2/manifest.ts

@@ -271,6 +271,54 @@ export function withPortalEntry(
   };
 }
 
+/**
+ * Adds the gateway entry a gateway deploy learned. Only public values: the base URL and what the platform says the
+ * gateway can do. Entries of other services are kept as they are.
+ */
+export function withGatewayEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    provider: string;
+    baseUrl: string;
+    capabilities: Record<string, boolean>;
+    openapiUrl?: string;
+    openapiHash?: string;
+    keyHeaderName?: string;
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  const baseUrl = info.baseUrl.replace(/\/+$/, "");
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      gateway: {
+        ...base.services.gateway,
+        provider: info.provider,
+        status: "ready",
+        baseUrl,
+        audience: baseUrl,
+        capabilities: info.capabilities,
+        ...(info.openapiUrl ? { openapiUrl: info.openapiUrl } : {}),
+        ...(info.openapiHash ? { openapiHash: info.openapiHash } : {}),
+        ...(info.keyHeaderName ? { keyHeaderName: info.keyHeaderName } : {}),
+      },
+    },
+  };
+}
+
 /** Replaces `services.json` atomically. Public values only: this file ships inside the portal. */
 export async function writeManifest(
   state: Pick<StatePaths, "dir">,
@@ -291,3 +339,25 @@ export async function writeManifest(
     throw error;
   }
 }
+
+/**
+ * Drops the entries of services that were torn down. The file is deleted when no service is left, because a
+ * manifest with no services says nothing and would only look like a deployed project.
+ */
+export async function removeServicesFromManifest(
+  state: Pick<StatePaths, "dir">,
+  names: readonly ManifestServiceName[],
+): Promise<void> {
+  const existing = await readManifest(state);
+  if (!existing) return;
+  const services = Object.fromEntries(
+    Object.entries(existing.services).filter(
+      ([name]) => !(names as readonly string[]).includes(name),
+    ),
+  );
+  if (Object.keys(services).length === 0) {
+    await rm(manifestPathFor(state), { force: true });
+    return;
+  }
+  await writeManifest(state, { ...existing, services });
+}

package/src/config/v2/resolve.ts

@@ -35,6 +35,7 @@ export type ResolvedGateway = {
   /** Absolute paths. */
   specs: string[];
   auth?: NonNullable<ConfigV2["gateway"]>["auth"];
+  export?: NonNullable<ConfigV2["gateway"]>["export"];
   policies: NonNullable<NonNullable<ConfigV2["gateway"]>["policies"]>;
 };
 
@@ -149,6 +150,7 @@ export function resolveConfigV2(
       },
       specs: gateway.specs.map((spec) => path.resolve(configDir, spec)),
       auth: gateway.auth,
+      export: gateway.export,
       policies: gateway.policies ?? {},
     };
   }