@lukoweb/apitogo 0.2.2 → 0.2.10

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.10",
   "type": "module",
   "sideEffects": [
     "**/*.css",

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,24 @@ 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 {
+  type DerivedCorsSite,
+  derivedCorsSites,
+  type GatewayConfigBody,
+  gatewayConfigBody,
+  stableJson,
+} from "./gateway-request.js";
 export {
   consoleLinks,
   planPortal,
@@ -84,6 +93,7 @@ export {
   planAddService,
   planRemoveService,
   SERVICES,
+  clearProjectId,
   ServiceEditError,
   setProjectId,
   type ServiceEdit,
@@ -91,6 +101,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 ?? {},
     };
   }

package/src/config/v2/rules.ts

@@ -253,11 +253,64 @@ function isIpLiteral(hostname: string): boolean {
   return /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.startsWith("[");
 }
 
+/** The credential the gateway sends to the origin: a header needs a name and a secret; mtls is not available yet. */
+function originAuthRules(
+  origin: NonNullable<ResolvedConfigV2["gateway"]>["origin"],
+  out: Collector,
+) {
+  const auth = origin.auth;
+  if (!auth) return;
+  const base = "gateway.origin.auth";
+  if (auth.type === "header") {
+    if (!auth.name)
+      out.error({
+        code: "GATEWAY_ORIGIN_INCOMPLETE",
+        path: `${base}.name`,
+        message: "origin.auth.type is header, so origin.auth.name is required.",
+        hint: 'For example: "X-Origin-Key".',
+      });
+    if (!auth.value)
+      out.error({
+        code: "GATEWAY_ORIGIN_INCOMPLETE",
+        path: `${base}.value`,
+        message:
+          "origin.auth.type is header, so origin.auth.value is required.",
+        hint: 'A secret reference, for example "secret:ORIGIN_KEY". Store it with `apitogo secrets set ORIGIN_KEY`.',
+      });
+  } else if (auth.type === "none" && (auth.name || auth.value)) {
+    out.error({
+      code: "GATEWAY_ORIGIN_INVALID",
+      path: base,
+      message: "origin.auth.type is none, but a name or value is set.",
+      hint: 'Remove them, or set the type to "header".',
+    });
+  } else if (auth.type === "mtls") {
+    out.error({
+      code: "GATEWAY_CAPABILITY_UNSUPPORTED",
+      path: `${base}.type`,
+      message:
+        "Client certificates (mtls) for the origin are not available yet.",
+      hint: 'Use type "header" with a secret.',
+    });
+  }
+}
+
 async function gatewayRules(resolved: ResolvedConfigV2, out: Collector) {
   const gateway = resolved.gateway;
   if (!gateway?.enabled) return;
   const origin = gateway.origin;
 
+  (gateway.policies.cors ?? []).forEach((site, index) => {
+    const { pathname, search, hash } = new URL(site);
+    if (pathname === "/" && !search && !hash && !site.endsWith("/")) return;
+    out.error({
+      code: "GATEWAY_CORS_ORIGIN_INVALID",
+      path: `gateway.policies.cors[${index}]`,
+      message: `"${site}" is not a browser origin: it has a path, a query or a trailing slash.`,
+      hint: `Use only scheme and host, for example "${new URL(site).origin}".`,
+    });
+  });
+
   if (origin.mode === "managed") {
     for (const field of ["source", "runtime", "runtimeVersion"] as const) {
       if (!origin[field]) {
@@ -340,6 +393,17 @@ async function gatewayRules(resolved: ResolvedConfigV2, out: Collector) {
     }
   }
 
+  originAuthRules(origin, out);
+  if (gateway.specs.length > 1) {
+    out.warn({
+      code: "GATEWAY_SPEC_INVALID",
+      path: "gateway.specs",
+      message:
+        "gateway.specs lists several files, but the platform takes one OpenAPI file per gateway, so deploy will refuse it.",
+      hint: "Merge them into one file.",
+    });
+  }
+
   for (const [index, spec] of gateway.specs.entries())
     await specRule(spec, index, resolved, out);
 

package/src/config/v2/schema.ts

@@ -60,6 +60,20 @@ const GatewayOriginSchema = z.strictObject({
   runtimeVersion: nonEmpty.optional(),
   exclude: pathList.optional(),
   url: httpsUrl.optional(),
+  /** Path the platform probes to check the origin, for example `/health`. */
+  healthPath: z
+    .string()
+    .regex(/^\/(?!\/)/, { error: 'must start with a single "/"' })
+    .optional(),
+  timeoutSeconds: z.int().min(1).max(120).optional(),
+  /** What the gateway sends to the origin as credential. The value is always a secret reference. */
+  auth: z
+    .strictObject({
+      type: z.enum(["none", "header", "mtls"]),
+      name: nonEmpty.optional(),
+      value: secretRef.optional(),
+    })
+    .optional(),
 });
 
 export const GatewaySchema = z.strictObject({
@@ -67,6 +81,10 @@ export const GatewaySchema = z.strictObject({
   provider: nonEmpty.optional(),
   origin: GatewayOriginSchema,
   specs: z.array(path).min(1, { error: "needs at least one OpenAPI file" }),
+  /** Who may read the OpenAPI file the platform publishes for this gateway. Default: public. */
+  export: z
+    .strictObject({ access: z.enum(["public", "authenticated"]).optional() })
+    .optional(),
   auth: z
     .strictObject({
       mode: z.enum(["identity", "oidc"]),
@@ -77,19 +95,35 @@ export const GatewaySchema = z.strictObject({
     .optional(),
   policies: z
     .strictObject({
+      access: z
+        .strictObject({
+          jwt: z.boolean().optional(),
+          apiKey: z.boolean().optional(),
+          apiKeyHeader: nonEmpty.optional(),
+          bindKeyToToken: z.boolean().optional(),
+        })
+        .optional(),
       rateLimit: z
         .strictObject({
           calls: z.int().positive(),
           periodSeconds: z.int().positive(),
+          scope: z.enum(["key", "entitlement"]).optional(),
         })
         .optional(),
       quota: z
         .strictObject({
           calls: z.int().positive(),
           periodDays: z.int().min(1),
+          scope: z.enum(["key", "entitlement"]).optional(),
         })
         .optional(),
       cors: z.array(z.url()).optional(),
+      operations: z
+        .strictObject({
+          public: z.array(nonEmpty).optional(),
+          deny: z.array(nonEmpty).optional(),
+        })
+        .optional(),
     })
     .optional(),
 });

package/src/config/v2/services.ts

@@ -642,3 +642,20 @@ export async function setProjectId(
   await writeConfig(resolved.configPath, next);
   return true;
 }
+
+/** Removes `project.id` when it is the given id: the project is gone, so the link would only point at nothing. */
+export async function clearProjectId(
+  dir: string,
+  projectId: string,
+): Promise<boolean> {
+  const { config, resolved } = loadConfigV2(dir);
+  if (config.project?.id !== projectId) return false;
+  const { id: _id, ...project } = config.project;
+  const { project: _old, ...rest } = config;
+  const next = reparse(resolved.configPath, {
+    ...rest,
+    ...(Object.keys(project).length > 0 ? { project } : {}),
+  });
+  await writeConfig(resolved.configPath, next);
+  return true;
+}