@smthrs/flow 1.0.0-rc.8 → 1.0.0-rc.9

package/src/DurableClock.ts

@@ -11,6 +11,7 @@
  * @since 0.1.0
  */
 
+import * as Clock from "effect/Clock"
 import type * as Crypto from "effect/Crypto"
 import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
@@ -56,6 +57,28 @@ const durationFromInput = (input: Duration.Input, field: string): Duration.Durat
   return parsed.value
 }
 
+/**
+ * The latest due time a durable timer records, in epoch milliseconds: a store
+ * keeps a clock's due time as a safe integer.
+ *
+ * @private
+ */
+const latestDueAtMs = Number.MAX_SAFE_INTEGER
+
+/**
+ * Parses a clock's own duration, which a store adds to the current time and
+ * records, so it is at most {@link latestDueAtMs} milliseconds.
+ *
+ * @private
+ */
+const clockDuration = (input: Duration.Input): Duration.Duration => {
+  const duration = durationFromInput(input, "duration")
+  if (Duration.toMillis(duration) > latestDueAtMs) {
+    throw new RangeError(`DurableClock: "duration" must be at most ${latestDueAtMs} milliseconds.`)
+  }
+  return duration
+}
+
 const makeClock = (name: string, duration: Duration.Duration): DurableClock => ({
   [TypeId]: TypeId,
   name,
@@ -66,18 +89,27 @@ const makeClock = (name: string, duration: Duration.Duration): DurableClock => (
 /**
  * Declares one durable clock after validating its finite nonnegative duration.
  *
+ * Throws a `RangeError` for a malformed, infinite or negative duration, or one
+ * longer than `Number.MAX_SAFE_INTEGER` milliseconds: a durable store records
+ * a clock's due time as a safe integer.
+ *
  * @category constructors
  * @since 0.1.0
  */
 export const make = (options: {
   readonly name: string
   readonly duration: Duration.Input
-}): DurableClock => makeClock(options.name, durationFromInput(options.duration, "duration"))
+}): DurableClock => makeClock(options.name, clockDuration(options.duration))
 
 /**
  * Waits inside a flow, using an in-memory action for durations at or
  * below the threshold and scheduling a durable clock for longer durations.
  *
+ * Throws a `RangeError` for the same durations {@link make} refuses, and for
+ * a malformed, infinite or negative threshold. A durable sleep that would
+ * wake after epoch millisecond `Number.MAX_SAFE_INTEGER` dies with a
+ * `RangeError` instead of arming its clock.
+ *
  * @category sleeping
  * @since 0.1.0
  */
@@ -99,7 +131,7 @@ export const sleep = (
   Crypto.Crypto | FlowRuntime | FlowInstance
 > => {
   const name = options.name
-  const duration = durationFromInput(options.duration, "duration")
+  const duration = clockDuration(options.duration)
   const inMemoryThreshold = durationFromInput(
     options.inMemoryThreshold ?? defaultInMemoryThreshold,
     "inMemoryThreshold"
@@ -119,6 +151,17 @@ export const sleep = (
       })
     }
 
+    // A due time past the latest one a store records would fail the park
+    // write deep in the engine, so the sleep refuses it here by name.
+    const now = yield* Clock.currentTimeMillis
+    if (now + Duration.toMillis(duration) > latestDueAtMs) {
+      return yield* Effect.die(
+        new RangeError(
+          `DurableClock: "${name}" would wake after epoch millisecond ${latestDueAtMs}, ` +
+            `the latest due time a durable timer records.`
+        )
+      )
+    }
     const engine = yield* FlowRuntime
     const instance = yield* FlowInstance
     const clock = makeClock(name, duration)

package/src/Flow/make.ts

@@ -99,7 +99,8 @@ interface MakeOptions<
   readonly maxRounds?: number | undefined
   /**
    * How long one execution may take, counted from its journaled first start.
-   * A positive finite duration; see {@link Flow.deadline}.
+   * A positive finite duration of at most `Number.MAX_SAFE_INTEGER`
+   * milliseconds; see {@link Flow.deadline}.
    */
   readonly deadline?: Duration.Input | undefined
   readonly annotations?: Context.Context<never>
@@ -222,6 +223,11 @@ export const make: {
   ) {
     throw new RangeError(`Flow.make: "${tag}" deadline must be a positive finite duration`)
   }
+  // The durable clock that enforces a deadline is due at its start plus the
+  // deadline, and a store records that due time as a safe integer.
+  if (deadline !== undefined && Duration.toMillis(deadline) > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError(`Flow.make: "${tag}" deadline must be at most ${Number.MAX_SAFE_INTEGER} ms`)
+  }
   // Captured here, where the stack still names the author's file, and carried
   // as a non-enumerable property so no digest can see it
   // (`internal/DeclarationSite.ts`).

package/src/HumanTask.ts

@@ -680,7 +680,9 @@ const budgetOf = (payload: Payload): Effect.Effect<number, HumanTaskFailed> => {
 const deadlineOf = (payload: Payload): Effect.Effect<Duration.Duration | undefined, HumanTaskFailed> => {
   const timeoutMs = payload.timeoutMs
   if (timeoutMs === undefined) return Effect.succeed(undefined)
-  return Number.isFinite(timeoutMs) && timeoutMs >= 0
+  // The timeout clock is due at its start plus the deadline, and a durable
+  // store records that due time as a safe integer.
+  return Number.isFinite(timeoutMs) && timeoutMs >= 0 && timeoutMs <= Number.MAX_SAFE_INTEGER
     ? Effect.succeed(Duration.millis(timeoutMs))
     : Effect.fail(
       failed(
@@ -688,8 +690,8 @@ const deadlineOf = (payload: Payload): Effect.Effect<Duration.Duration | undefin
         "request_invalid",
         0,
         [],
-        `${tag} was called with timeoutMs ${timeoutMs}. A deadline is a finite number of ` +
-          "milliseconds that is not negative; the question would be over before it was asked, or " +
+        `${tag} was called with timeoutMs ${timeoutMs}. A deadline is a number of milliseconds ` +
+          `from 0 to ${Number.MAX_SAFE_INTEGER}; the question would be over before it was asked, or ` +
           "never over at all."
       )
     )