@reventlessdev/reventless-aws 3.0.0-alpha.201 → 3.0.0-alpha.203

package/src/adapter/Runtime/ApiSchemaPush_Runtime.mjs

@@ -0,0 +1,197 @@
+// Runtime-pure push engine for the admin ApiSchemaPush SideEffect
+// (docs/plans/event-sourced-fragment-registries.md § Reactive writer design).
+//
+// The ApiFragmentRegistry singleton aggregate's behaviour emits ApiSchemaComputed
+// { snapshot } — the WHOLE per-plugin fragment set folded from the aggregate's own
+// consistent single-partition state after each change. The ApiSchemaPush SideEffect
+// (compiled from ApiSchemaPush.res) subscribes to that event via the aggregate's
+// DynamoDB stream (single-shard for a singleton → naturally serialized, no concurrent
+// StartSchemaCreation), and hands the snapshot here.
+//
+// This module stitches one AWS-decorated schema per target API from the snapshot
+// (identical decoration to the deploy path via the runtime-pure
+// AppSync_SdlDecorate.planAwsPushes), pushes each behind the catastrophic-shrink
+// guard, and writes the outcome back with RecordApiFragmentPush onto the
+// ApiFragmentRegistry aggregate's command topic so the deploy waiter can poll
+// Platform_ApiFragments.
+//
+// Runtime-purity discipline: NO @pulumi imports (this loads in the SideEffectHandler
+// Lambda — see reference_pulumi_leaks_into_lambda_runtime_graph). All config is read
+// from env at invocation time; the AppSync push uses the AppSync SDK directly.
+
+import { makeQueueRef, log } from "./HandlerFactoryHelpers.mjs";
+import { publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
+import { planAwsPushes } from "@reventlessdev/reventless-aws/src/components/Api/AppSync_SdlDecorate.res.mjs";
+import {
+  countRootTypeFields,
+  isCatastrophicSchemaShrink,
+} from "@reventlessdev/reventless-core/src/components/Api/GraphQL_Stitcher.res.mjs";
+import {
+  baseFragment as adminBaseFragment,
+  systemCallerFieldNames,
+} from "@reventlessdev/reventless-core/src/admin/AdminApi.res.mjs";
+
+const COMP = "apiSchemaPush";
+
+// ── AppSync push primitives (mirror AdminEventCollectorEntryPoint.mjs) ──────────
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Push the SDL. Bounded retry on the AppSync API-level lock ("Schema is currently being
+// altered" / ConcurrentModification) — the legacy connect-driven mkUpdateApiSchema still
+// pushes until Plan Phase 4, and a standalone-service push can also contend. The lock
+// clears in seconds, so this is NOT the plan's rejected lagging-read retry (that had no
+// ceiling). The singleton aggregate's single-shard stream already serializes THIS writer
+// against itself; this only covers cross-writer contention.
+async function updateAppSyncSchema(apiId, sdl) {
+  const { AppSyncClient, StartSchemaCreationCommand } = await import("@aws-sdk/client-appsync");
+  const client = new AppSyncClient({});
+  const maxAttempts = 6;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await client.send(new StartSchemaCreationCommand({ apiId, definition: sdl }));
+      return;
+    } catch (e) {
+      const msg = (e && e.message) || String(e);
+      const locked = /being altered|ConcurrentModification|currently in the process/i.test(msg);
+      if (!locked || attempt >= maxAttempts) throw e;
+      const backoff = Math.min(1000 * 2 ** (attempt - 1), 8000);
+      log.warn(`schema push contended (${msg}) — retry ${attempt}/${maxAttempts} in ${backoff}ms`, { comp: COMP });
+      await sleep(backoff);
+    }
+  }
+}
+
+// Current live schema as SDL for the shrink guard. "" (not error) when the API has
+// no schema yet or introspection fails — the caller treats "" as "no baseline".
+async function getCurrentSchemaSdl(apiId) {
+  try {
+    const { AppSyncClient, GetIntrospectionSchemaCommand } = await import("@aws-sdk/client-appsync");
+    const client = new AppSyncClient({});
+    const resp = await client.send(new GetIntrospectionSchemaCommand({ apiId, format: "SDL" }));
+    if (!resp || !resp.schema) return "";
+    return Buffer.from(resp.schema).toString("utf-8");
+  } catch (e) {
+    log.warn(`could not introspect current schema (${(e && e.message) || e}) — skipping shrink guard`, { comp: COMP });
+    return "";
+  }
+}
+
+function parseShrinkThreshold(raw) {
+  const n = raw ? Number(raw) : NaN;
+  return Number.isFinite(n) && n > 0 && n < 1 ? n : 0.5;
+}
+
+// Emit the SchemaShrinkRejected CloudWatch metric via EMF (raw console.log — must
+// stay unwrapped so CloudWatch's EMF auto-detect fires).
+function emitShrinkRejectionMetric(apiId, currentRootFields, newRootFields) {
+  try {
+    // eslint-disable-next-line no-console
+    console.log(
+      JSON.stringify({
+        _aws: {
+          Timestamp: Date.now(),
+          CloudWatchMetrics: [
+            {
+              Namespace: "Reventless/Runtime",
+              Dimensions: [["ApiId"]],
+              Metrics: [{ Name: "SchemaShrinkRejected", Unit: "Count" }],
+            },
+          ],
+        },
+        ApiId: apiId,
+        SchemaShrinkRejected: 1,
+        currentRootFields,
+        newRootFields,
+      })
+    );
+  } catch {
+    // metric emission is best-effort
+  }
+}
+
+// ── Config (deploy-derived, injected as Lambda env by the admin SideEffectHandler) ──
+
+function readConfig() {
+  const na = (v) => (v && v !== "NOT_AVAILABLE" ? v : "");
+  const domainApiId = na(process.env["API_SCHEMA_PUSH_DOMAIN_API_ID"]);
+  const platformApiId = na(process.env["API_SCHEMA_PUSH_PLATFORM_API_ID"]) || domainApiId;
+  return {
+    domainApiId,
+    platformApiId,
+    splitApi: process.env["API_SCHEMA_PUSH_SPLIT_API"] === "true",
+    clonerEnabled: process.env["API_SCHEMA_PUSH_CLONER"] === "true",
+    cmdTopicUrl: na(process.env["API_SCHEMA_PUSH_CMD_TOPIC_URL"]),
+  };
+}
+
+// Write RecordApiFragmentPush back per plugin onto the ApiFragmentRegistry aggregate's
+// command topic (FIFO, singleton id="registry"). @noApi + idempotent — a no-op in the
+// aggregate behaviour if the plugin was deregistered in the meantime.
+async function recordPushOutcomes(cmdTopicUrl, pluginIds, ok, message) {
+  if (!cmdTopicUrl || pluginIds.length === 0) return;
+  const publisher = sqsPublishJsons(makeQueueRef(cmdTopicUrl), "SQS_FIFO");
+  const at = new Date().toISOString();
+  const commandJsons = pluginIds.map((pluginId) => ({
+    id: "registry",
+    meta: { service: "ApiFragmentRegistry", time: at, msgId: "pending", correlationId: pluginId },
+    commandJson: { TAG: "RecordApiFragmentPush", pluginId, ok, message, at },
+  }));
+  try {
+    await publisher(commandJsons);
+  } catch (e) {
+    log.error(`RecordApiFragmentPush dispatch failed: ${(e && e.message) || e}`, { comp: COMP });
+  }
+}
+
+// ── Entry point ────────────────────────────────────────────────────────────────
+
+// snapshot: array of { pluginId, encoded, protocol, apiTarget } — the consistent
+// registry contents after the triggering change, carried on the ApiSchemaComputed event.
+export async function pushApiSchema(snapshot) {
+  const cfg = readConfig();
+  const entries = Array.isArray(snapshot) ? snapshot.filter((e) => e && typeof e.encoded === "string" && e.encoded) : [];
+  const pluginIds = [...new Set(entries.map((e) => e.pluginId).filter((p) => typeof p === "string"))];
+  if (!cfg.cmdTopicUrl) {
+    log.warn("ApiSchemaPush: no command-topic URL configured — skipping", { comp: COMP });
+    return;
+  }
+
+  // Fragments straight from the consistent snapshot — NO eventually-consistent read.
+  const fragments = entries.map((e) => ({
+    encoded: e.encoded,
+    protocol: typeof e.protocol === "string" ? e.protocol : "graphql",
+    target: e.apiTarget === "Platform" ? "Platform" : "Domain",
+  }));
+
+  const rawAdminBase = adminBaseFragment(cfg.clonerEnabled);
+  const plans = planAwsPushes(rawAdminBase, systemCallerFieldNames, fragments, cfg.splitApi);
+
+  let ok = true;
+  let message = "";
+  for (const plan of plans) {
+    const apiId = plan.api === "PlatformApi" ? cfg.platformApiId : cfg.domainApiId;
+    if (!apiId) continue;
+    const threshold = parseShrinkThreshold(process.env["RUNTIME_SCHEMA_SHRINK_THRESHOLD"]);
+    const currentSdl = await getCurrentSchemaSdl(apiId);
+    if (isCatastrophicSchemaShrink(currentSdl, plan.sdl, threshold)) {
+      const cur = countRootTypeFields(currentSdl, "Mutation") + countRootTypeFields(currentSdl, "Query");
+      const nw = countRootTypeFields(plan.sdl, "Mutation") + countRootTypeFields(plan.sdl, "Query");
+      log.error(`ABORTED schema push for ${plan.api} (${apiId}): ${nw} root field(s) vs ${cur} live (threshold ${threshold}).`, { comp: COMP });
+      emitShrinkRejectionMetric(apiId, cur, nw);
+      ok = false;
+      message = `shrink guard aborted push for ${plan.api}`;
+      continue;
+    }
+    try {
+      await updateAppSyncSchema(apiId, plan.sdl);
+      log.info(`schema push OK: ${plan.api} (${apiId})`, { comp: COMP });
+    } catch (e) {
+      ok = false;
+      message = (e && e.message) || String(e);
+      log.error(`schema push FAILED: ${plan.api} (${apiId}): ${message}`, { comp: COMP });
+    }
+  }
+
+  await recordPushOutcomes(cfg.cmdTopicUrl, pluginIds, ok, message);
+}

package/src/adapter/Runtime/SideEffectHandlerRuntime_Builder_Single.res

@@ -15,6 +15,15 @@ let sideEffectInfos: dict<sideEffectInfo> = Dict.make()
 let registerSideEffectHandler = (~sideEffectHandlerName, ~sideEffectModulePaths) =>
   sideEffectInfos->Dict.set(sideEffectHandlerName, {sideEffectModulePaths: sideEffectModulePaths})
 
+// Extra Lambda env vars contributed by bespoke side effects (e.g. admin ApiSchemaPush).
+// The shared "AllSideEffectHandlers" Lambda is built once in finish(); all registered
+// entries are merged onto its env there. Deploy-derived config only — never overrides
+// HANDLER_CONFIG.
+let extraEnvVarsAll: dict<Pulumi.Input.t<string>> = Dict.make()
+
+let registerExtraEnv = (~extraEnvVars: dict<Pulumi.Input.t<string>>) =>
+  extraEnvVars->Dict.forEachWithKey((v, k) => extraEnvVarsAll->Dict.set(k, v))
+
 type storedSpec = {
   componentName: string,
   parentResource: Pulumi.Resource.t,
@@ -143,6 +152,12 @@ let finish = () =>
 
         let envVars: dict<Pulumi.Input.t<string>> = Dict.make()
         envVars->Dict.set("HANDLER_CONFIG", handlerConfigOutput->Pulumi.Output.asInput)
+        // Merge bespoke side-effect config (never overrides HANDLER_CONFIG).
+        extraEnvVarsAll->Dict.forEachWithKey((v, k) =>
+          if k != "HANDLER_CONFIG" {
+            envVars->Dict.set(k, v)
+          }
+        )
 
         // Build AssetArchive: static re-export + user packages
         let {code, sourceCodeHash} = Util_Bundle.buildCodeArchive(
@@ -161,6 +176,38 @@ let finish = () =>
           ~opts,
         )
 
+        // The admin ApiSchemaPush side effect (the only extra-env contributor) pushes the
+        // stitched schema to AppSync via StartSchemaCreation and reads the live schema for
+        // the shrink guard. Grant those AppSync perms to the shared side-effect-handler
+        // Lambda role ONLY when a bespoke side effect registered config — Task-only
+        // deployments keep the narrow default perimeter. Mirrors the admin EventCollector's
+        // AllowAdminStartSchemaCreation grant (PluginRuntime_Builder).
+        if extraEnvVarsAll->Dict.keysToArray->Array.length > 0 {
+          let _ = PulumiAws.IAM.RolePolicy.make(
+            ~name="AllSideEffectHandlers-appsyncSchemaPush",
+            ~args={
+              policy: PulumiAws.PolicyDocument.make(
+                ~id="AllSideEffectHandlersAppsyncSchemaPushPolicy",
+                ~statements=[
+                  {
+                    sid: "AllowSideEffectStartSchemaCreation",
+                    effect: Allow,
+                    actions: Actions([
+                      "appsync:StartSchemaCreation",
+                      "appsync:GetSchemaCreationStatus",
+                      "appsync:GetIntrospectionSchema",
+                    ]),
+                    resources: AllResources,
+                  },
+                ],
+              )
+              ->PulumiAws.PolicyDocument.toJsonString
+              ->Pulumi.Input.make,
+              role: runtime.parts.lambdaRole.id->Pulumi.Output.asInput,
+            },
+          )
+        }
+
         let channelSpecs = storedSpecs->Array.map(({channelSpec}) => channelSpec)
         let _connectResources = EventCollectorChannel.connect(
           ~name="AllSideEffectHandlers",

package/src/adapter/Runtime/SideEffectHandlerRuntime_Builder_Single.res.mjs

@@ -1,11 +1,14 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Aws from "@pulumi/aws";
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
 import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/components/Component.res.mjs";
+import * as PolicyDocument$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/IAM/PolicyDocument.res.mjs";
 import * as Util_Bundle$ReventlessAws from "../../util/Util_Bundle.res.mjs";
 import * as RuntimeEnvironment_Lambda$ReventlessAws from "./RuntimeEnvironment_Lambda.res.mjs";
 import * as EventCollectorChannel_DynamoDbStream$ReventlessAws from "../EventCollector/EventCollectorChannel_DynamoDbStream.res.mjs";
@@ -20,6 +23,14 @@ function registerSideEffectHandler(sideEffectHandlerName, sideEffectModulePaths)
   };
 }
 
+let extraEnvVarsAll = {};
+
+function registerExtraEnv(extraEnvVars) {
+  Stdlib_Dict.forEachWithKey(extraEnvVars, (v, k) => {
+    extraEnvVarsAll[k] = v;
+  });
+}
+
 let storedSpecs = [];
 
 let grandParent = {
@@ -99,8 +110,29 @@ function finish() {
       let handlerConfigOutput = Pulumi.all(handlerOutputs).apply(handlers => `{"handlers":[` + handlers.join(",") + `]}`);
       let envVars = {};
       envVars["HANDLER_CONFIG"] = handlerConfigOutput;
+      Stdlib_Dict.forEachWithKey(extraEnvVarsAll, (v, k) => {
+        if (k !== "HANDLER_CONFIG") {
+          envVars[k] = v;
+          return;
+        }
+      });
       let match$1 = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/SideEffectEntryPoint.mjs", packageDirs, undefined);
       let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllSideEffectHandlers", "Reactor", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, undefined, opts);
+      if (Object.keys(extraEnvVarsAll).length !== 0) {
+        new (Aws.iam.RolePolicy)("AllSideEffectHandlers-appsyncSchemaPush", {
+          policy: PolicyDocument$PulumiAws.toJsonString(PolicyDocument$PulumiAws.make(undefined, "AllSideEffectHandlersAppsyncSchemaPushPolicy", [{
+              Sid: "AllowSideEffectStartSchemaCreation",
+              Effect: "Allow",
+              Action: [
+                "appsync:StartSchemaCreation",
+                "appsync:GetSchemaCreationStatus",
+                "appsync:GetIntrospectionSchema"
+              ],
+              Resource: "*"
+            }])),
+          role: runtime.parts.lambdaRole.id
+        });
+      }
       let channelSpecs = storedSpecs.map(param => param.channelSpec);
       EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllSideEffectHandlers", channelSpecs, runtime, opts);
     } else {
@@ -120,6 +152,8 @@ export {
   log,
   sideEffectInfos,
   registerSideEffectHandler,
+  extraEnvVarsAll,
+  registerExtraEnv,
   storedSpecs,
   grandParent,
   forEventCollector,

package/src/components/SideEffectHandler_Single.res

@@ -22,6 +22,7 @@ module Make = (): ReventlessCore.SideEffectHandler.T => {
     ~resourceNaming,
     ~memorySize=?,
     ~timeout=?,
+    ~extraEnvVars=?,
     ~opts=?,
   ) => {
     let component = Inner.make(
@@ -49,6 +50,13 @@ module Make = (): ReventlessCore.SideEffectHandler.T => {
       ~sideEffectModulePaths,
     )
 
+    // Bespoke side effects (e.g. admin ApiSchemaPush) inject deploy-derived config as
+    // extra Lambda env vars, merged onto the shared side-effect-handler Lambda in finish().
+    switch extraEnvVars {
+    | Some(env) => EventCollectorRuntimeBuilder.registerExtraEnv(~extraEnvVars=env)
+    | None => ()
+    }
+
     component
   }
 }

package/src/components/SideEffectHandler_Single.res.mjs

@@ -34,10 +34,13 @@ function Make($star) {
     forEventCollector: SideEffectHandlerRuntime_Builder_Single$ReventlessAws.forEventCollector,
     finish: SideEffectHandlerRuntime_Builder_Single$ReventlessAws.finish
   });
-  let make = (name, sideEffects, allEventTopics, allCommandTopics, targets, queryEngine, scheduler, resourceNaming, memorySize, timeout, opts) => {
-    let component = Inner.make(name, sideEffects, allEventTopics, allCommandTopics, targets, queryEngine, scheduler, resourceNaming, memorySize, timeout, opts);
+  let make = (name, sideEffects, allEventTopics, allCommandTopics, targets, queryEngine, scheduler, resourceNaming, memorySize, timeout, extraEnvVars, opts) => {
+    let component = Inner.make(name, sideEffects, allEventTopics, allCommandTopics, targets, queryEngine, scheduler, resourceNaming, memorySize, timeout, undefined, opts);
     let sideEffectModulePaths = sideEffects.map(SE => Util_Bundle$ReventlessAws.getModuleSpecifier(SE.moduleUrl));
     SideEffectHandlerRuntime_Builder_Single$ReventlessAws.registerSideEffectHandler(name, sideEffectModulePaths);
+    if (extraEnvVars !== undefined) {
+      SideEffectHandlerRuntime_Builder_Single$ReventlessAws.registerExtraEnv(extraEnvVars);
+    }
     return component;
   };
   return {