@reventlessdev/reventless-core 3.0.0-alpha.171 → 3.0.0-alpha.172

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.172 (2026-07-17)
+
+### Bug Fixes
+
+* **plugin:** scale heartbeat disconnect grace and enforce single-source interval ([7ba8fb7](https://github.com/ReventlessDev/reventless-core/commit/7ba8fb7bfbe023aba7b538329d2489f939b7fcea))
+
+
 # 3.0.0-alpha.171 (2026-07-17)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.171",
+  "version": "3.0.0-alpha.172",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,14 +30,14 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.29",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
-    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
-    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
-    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
+    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
+    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/reventless-infra": "3.0.0-alpha.102",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.28",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.28",
+    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
     "@reventlessdev/reventless-spec": "3.0.0-alpha.79"
   },
   "devDependencies": {

package/src/components/Heartbeat/Heartbeat.res

@@ -11,13 +11,13 @@ module type T = {
   let connect: (
     ~runtime: Runtime.environment<runtimeParts>,
     ~remoteChannel: CommandTopic_Adapter.remoteChannel,
-    ~timeout: int=?,
+    ~timeout: int,
     component,
   ) => unit
 
   let makeHandler: (
     ~id: string,
-    ~timeout: int=?,
+    ~timeout: int,
     ~publishToPluginExtensionPoint: CommandTopic.publishJsons,
   ) => Pulumi.Output.t<Runtime.eventHandler<unit, 'context, unit>>
 

package/src/components/Heartbeat/Heartbeat_Builder.res

@@ -5,7 +5,7 @@ module Make = (Runner: Heartbeat_Adapter.Runner): (
 
   let construct = (_self, _name) => ()
 
-  let connect = (~runtime, ~remoteChannel, ~timeout=10, heartbeat) => {
+  let connect = (~runtime, ~remoteChannel, ~timeout, heartbeat) => {
     let heartbeatResource = heartbeat->Component.toPulumiResource
     let name =
       heartbeatResource.name
@@ -24,7 +24,7 @@ module Make = (Runner: Heartbeat_Adapter.Runner): (
     let _ = heartbeat->Component.setOutputs(outputs)
   }
 
-  let makeHandler = (~id, ~timeout=10, ~publishToPluginExtensionPoint) => {
+  let makeHandler = (~id, ~timeout, ~publishToPluginExtensionPoint) => {
     module Callback = Heartbeat_Callback.Make({
       let publishToPluginExtensionPoint = publishToPluginExtensionPoint
       let id = id

package/src/components/Heartbeat/Heartbeat_Builder.res.mjs

@@ -9,8 +9,7 @@ import * as Heartbeat_Callback$ReventlessCore from "./Heartbeat_Callback.res.mjs
 
 function Make(Runner) {
   let construct = (_self, _name) => {};
-  let connect = (runtime, remoteChannel, timeoutOpt, heartbeat) => {
-    let timeout = timeoutOpt !== undefined ? timeoutOpt : 10;
+  let connect = (runtime, remoteChannel, timeout, heartbeat) => {
     let heartbeatResource = Component$ReventlessCore.toPulumiResource(heartbeat);
     let name = ComponentType$ReventlessCore.name(Stdlib_Option.getOr(heartbeatResource.__name, "Unnamed"), Heartbeat$ReventlessCore.componentType);
     let opts_parent = heartbeatResource;
@@ -24,8 +23,7 @@ function Make(Runner) {
     };
     Component$ReventlessCore.setOutputs(heartbeat, outputs);
   };
-  let makeHandler = (id, timeoutOpt, publishToPluginExtensionPoint) => {
-    let timeout = timeoutOpt !== undefined ? timeoutOpt : 10;
+  let makeHandler = (id, timeout, publishToPluginExtensionPoint) => {
     let Callback = Heartbeat_Callback$ReventlessCore.Make({
       publishToPluginExtensionPoint: publishToPluginExtensionPoint,
       id: id,

package/src/plugin/component/Plugin_Builder.res

@@ -887,7 +887,11 @@ module Make = (
         | Some((_, pluginExtensionPointCommandTopicRemoteChannel)) =>
           // Notify platform hook that the EP channel is available (AWS extracts SQS URL for bundled heartbeat)
           Spec.hooks.onHeartbeatEpChannelAvailable->Option.forEach(hook =>
-            hook(pluginExtensionPointCommandTopicRemoteChannel->Obj.magic, ~pluginId=id)
+            hook(
+              pluginExtensionPointCommandTopicRemoteChannel->Obj.magic,
+              ~pluginId=id,
+              ~heartbeatInterval,
+            )
           )
           heartbeat->PluginRuntimeBuilder.forPluginHeartbeat(
             ~handler,

package/src/plugin/component/Plugin_Builder.res.mjs

@@ -545,7 +545,7 @@ function Make(Spec) {
           let handler = SpecificHeartbeat.makeHandler(id, heartbeatInterval, publishToPluginExtensionPoint);
           if (coreSetup !== undefined) {
             let pluginExtensionPointCommandTopicRemoteChannel$1 = coreSetup[1];
-            Stdlib_Option.forEach(Spec.hooks.onHeartbeatEpChannelAvailable, hook => hook(pluginExtensionPointCommandTopicRemoteChannel$1, id));
+            Stdlib_Option.forEach(Spec.hooks.onHeartbeatEpChannelAvailable, hook => hook(pluginExtensionPointCommandTopicRemoteChannel$1, id, heartbeatInterval));
             PluginRuntimeBuilder.forPluginHeartbeat(handler, none => SpecificHeartbeat.connect(none, pluginExtensionPointCommandTopicRemoteChannel$1, heartbeatInterval, heartbeat), undefined, undefined, heartbeat);
           } else {
             PluginRuntimeBuilder.forPluginHeartbeat(handler, param => {}, undefined, undefined, heartbeat);

package/src/plugin/component/Plugin_Helpers.res

@@ -957,7 +957,12 @@ type platformHooks = {
   onDcbEventLogCreated?: unknown => unit,
   onDcbCommandTopicCreated?: unknown => unit,
   onDcbSlicesCreated?: unknown => unit,
-  onHeartbeatEpChannelAvailable?: (unknown, ~pluginId: string) => unit,
+  // heartbeatInterval carries the plugin's heartbeat cadence so the AWS bundled
+  // heartbeat Lambda emits Heartbeat(interval) matching its EventBridge schedule
+  // rate. Both derive from the same heartbeatInterval; threading it here prevents
+  // the schedule-rate vs command-interval divergence that caused connect/disconnect
+  // flapping (schedule every 60min but Heartbeat(10) → 12min grace).
+  onHeartbeatEpChannelAvailable?: (unknown, ~pluginId: string, ~heartbeatInterval: int) => unit,
   // ── Admin → Plugin coordination ────────────────────────────────────────
   // Set by makePlatform after Admin.construct(); read by Plugin_Builder to
   // wire the local admin connection path (in-memory).  Starts as an empty

package/src/plugin/connect/PluginExtensionPoint_Plugin.res

@@ -5,6 +5,14 @@ open Reventless.Plugin
 
 module PluginExtensionPointSpec = ReventlessInfra.PluginExtensionPointSpec
 
+// Grace before a plugin is marked Disconnected once heartbeats stop, expressed in
+// whole minutes (schedules can only be created by minute). The margin scales with
+// the interval so large cadences keep real headroom: a fixed +2 gave a 60-min
+// heartbeat only ~3% slack, so a single late EventBridge beat + Lambda cold-start
+// could trip a spurious disconnect. `+ max(2, interval / 2)` keeps ≥ +2 min for
+// small intervals and ≥ +50% for large ones (5→7, 10→15, 60→90).
+let disconnectGrace = interval => interval + max(2, interval / 2)
+
 module type Spec = {
   let runtimeOps: PluginRuntimeOperations.operations
   let environment: string
@@ -145,10 +153,9 @@ module Make = (Spec: Spec) => {
       switch cmd {
       | PluginExtensionPointSpec.Heartbeat(interval) => [
           PublishCommand(Plugin.name(id), Delegate.Heartbeat(Plugin.version(id))),
-          // Re-create timeout (+2 minute to avoid toggling)
-          // 1 minute because Schedules can only be created by minute
-          // 1 additional minute to allow additional latency
-          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, interval + 2)),
+          // Re-arm the disconnect schedule with an interval-scaled grace so a
+          // single late beat doesn't trip a spurious disconnect (see disconnectGrace).
+          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, disconnectGrace(interval))),
         ]
       | RedetectPlugin(interval) => [
           // Deploy-time re-detect: drive Redetect (not Heartbeat) so an already-connected
@@ -156,7 +163,7 @@ module Make = (Spec: Spec) => {
           // re-arm the disconnect schedule exactly like a heartbeat so liveness tracking
           // continues from the deploy moment.
           PublishCommand(Plugin.name(id), Delegate.Redetect(Plugin.version(id))),
-          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, interval + 2)),
+          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, disconnectGrace(interval))),
         ]
       | ConnectPlugin(pluginDefinition) =>
         // Validate protocol versions declared by the connecting plugin.

package/src/plugin/connect/PluginExtensionPoint_Plugin.res.mjs

@@ -3,6 +3,7 @@
 import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
@@ -17,6 +18,10 @@ import * as PluginsReadModelSpec$ReventlessCore from "../lifecycle/PluginsReadMo
 import * as ExtensionPointMapping$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/ExtensionPointMapping.res.mjs";
 import * as PluginExtensionPointSpec$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/PluginExtensionPointSpec.res.mjs";
 
+function disconnectGrace(interval) {
+  return interval + Primitive_int.max(2, interval / 2 | 0) | 0;
+}
+
 function Make(Spec) {
   let forwardCommand = async (_id, command, extensionPointName, queryEngine) => {
     let jsons = await queryEngine.scan(PluginSpec$ReventlessCore.name, [
@@ -151,7 +156,7 @@ function Make(Spec) {
             _1: {
               TAG: "CreateDisconnectSchedule",
               _0: id,
-              _1: cmd._0 + 2 | 0
+              _1: disconnectGrace(cmd._0)
             }
           }
         ];
@@ -201,7 +206,7 @@ function Make(Spec) {
             _1: {
               TAG: "CreateDisconnectSchedule",
               _0: id,
-              _1: cmd._0 + 2 | 0
+              _1: disconnectGrace(cmd._0)
             }
           }
         ];
@@ -369,6 +374,7 @@ export {
   name,
   Id,
   PluginExtensionPointSpec,
+  disconnectGrace,
   Make,
   moduleUrl,
 }

package/tests/plugin/HeartbeatDisconnectGraceTest.res

@@ -0,0 +1,98 @@
+// Regression tests for the plugin-lifecycle heartbeat / disconnect margin.
+//
+// A plugin's liveness is scheduler-driven: every heartbeat re-arms a one-time
+// disconnect schedule, and if heartbeats stop the schedule fires and marks the
+// plugin Disconnected. Two independently-wired values must agree — the recurring
+// heartbeat *schedule rate* and the *interval carried inside the Heartbeat command*
+// (which drives CreateDisconnectSchedule). A deployed plugin once ran with schedule
+// rate(60min) but a Heartbeat(10) command (grace ~12min), so it reconnected for
+// ~12min after each hourly beat then sat Disconnected for the rest of the hour —
+// it flapped. See docs/plans/plugin-heartbeat-disconnect-margin-hardening.md.
+//
+// These tests pin the two guarantees that the fix provides at this layer:
+//   1. the disconnect grace scales with the interval (large cadences keep headroom);
+//   2. the disconnect schedule the EP mapping arms is derived from the *same*
+//      interval the Heartbeat/RedetectPlugin command carries — never a constant.
+// (The schedule-rate ⇄ command-interval single-source is additionally enforced at
+//  compile time now that Heartbeat_Builder's ~timeout is mandatory.)
+
+open JestGlobals
+
+module PluginExtensionPointSpec = ReventlessInfra.PluginExtensionPointSpec
+open ReventlessInfra.ExtensionPointMapping
+
+// The mapping functor only needs runtimeOps at directive-*execution* time; the
+// pure mapIncomingCommand under test never touches it, so a stub Spec suffices
+// (mirrors the Obj.magic stubbing already used in HeartbeatTest.res).
+module TestMapping = PluginExtensionPoint_Plugin.Make({
+  let runtimeOps = Obj.magic()
+  let environment = "test"
+  let updateApiSchema = None
+  let manageSubscriptions = None
+})
+
+// Pull the disconnect-schedule grace (in minutes) out of the actions a mapping
+// emits for an incoming command, if any.
+let graceFromActions = actions =>
+  actions->Array.findMap((action: commandAction<_, _>) =>
+    switch action {
+    | HandleDirective(_, PluginExtensionPointSpec.CreateDisconnectSchedule(_, timeout)) =>
+      Some(timeout)
+    | _ => None
+    }
+  )
+
+let meta = Message.generateMeta(~service="test", ~user="test")
+
+describe("disconnectGrace", () => {
+  // The observed-bug fix: the margin must scale, so a 60-min cadence keeps real
+  // headroom instead of the old fixed +2 (~3%).
+  testSync("scales with the interval (5→7, 10→15, 60→90)", () => {
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(5))->toBe(7)
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(10))->toBe(15)
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(60))->toBe(90)
+  })
+
+  testSync("always leaves at least a full interval of headroom past one beat", () => {
+    // Grace must exceed the interval (else a single beat's cadence trips a
+    // disconnect) and keep the historical ≥ +2 min floor for small intervals.
+    [1, 2, 5, 10, 30, 60, 120]->Array.forEach(interval => {
+      let grace = PluginExtensionPoint_Plugin.disconnectGrace(interval)
+      expect(grace > interval)->toBe(true)
+      expect(grace >= interval + 2)->toBe(true)
+    })
+  })
+
+  testSync("a 60-min cadence gets far more than the old fixed +2 grace", () => {
+    // The exact regression: interval 60 previously armed a 62-min disconnect.
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(60) > 62)->toBe(true)
+  })
+})
+
+describe("PluginExtensionPoint mapping arms the disconnect schedule from the beat interval", () => {
+  testSync("Heartbeat(interval) → CreateDisconnectSchedule(_, disconnectGrace(interval))", () => {
+    [5, 10, 60]->Array.forEach(interval => {
+      let actions = TestMapping.PluginMapping.mapIncomingCommand(
+        "Test@1",
+        PluginExtensionPointSpec.Heartbeat(interval),
+        meta,
+      )
+      expect(actions->graceFromActions)->toEqual(
+        Some(PluginExtensionPoint_Plugin.disconnectGrace(interval)),
+      )
+    })
+  })
+
+  testSync("RedetectPlugin(interval) arms the same interval-derived grace as a heartbeat", () => {
+    [5, 10, 60]->Array.forEach(interval => {
+      let actions = TestMapping.PluginMapping.mapIncomingCommand(
+        "Test@1",
+        PluginExtensionPointSpec.RedetectPlugin(interval),
+        meta,
+      )
+      expect(actions->graceFromActions)->toEqual(
+        Some(PluginExtensionPoint_Plugin.disconnectGrace(interval)),
+      )
+    })
+  })
+})