effect-cf 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # effect-cf
 
+## 0.51.0
+
+### Minor Changes
+
+- [#199](https://github.com/danieljvdm/effect-cf/pull/199) [`abe14de`](https://github.com/danieljvdm/effect-cf/commit/abe14de1f6d563ad000220bfe7b0d03266efaf12) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Bound Durable Object alarm failures and handler self-rearms with exponential backoff, a one-second floor, an eight-attempt no-progress budget and hourly parked recovery. Add content-free parking reports, durable status inspection, monotonic source progress and transactional min-merge scheduling.
+
+  Add an optional DurableObjectAlarm.ScheduleConfiguration reference, installed with Layer.succeed, for the retry floor, finite attempt budget, parked recovery interval and product repeat floor. Defaults remain one second, eight attempts, one hour and one minute. Validation preserves a one-second retry/repeat minimum and at most hourly parked recovery; increasing the budget cannot resume parked work without progress.
+
+  Dispatch and reconcile from indexed effective wake deadlines, with automatic migration of retained schedules, instead of scanning the backlog on every mutation. Failures retry independently and cannot block unrelated due work.
+
+  BREAKING: remove platform setAlarm, setAlarmAfter and deleteAlarm from the public storage and transaction wrappers. Migrate deadline writes to scheduleAlarm, earliest-deadline merges to scheduleAlarmEarlier, and atomic storage changes to alarms.transaction. Product repeatEvery schedules now require at least one minute by default; provide ScheduleConfiguration for a different product repeat floor. Remove ordered failure handling and ProcessDueAlarmsMode: drop options.mode and replace ordered failure policies/actions with retry. Enroll dependent work on completion events. Due alarms dispatch by effective wake deadline and storage key; retry deadlines remain separate from logical scheduledAt.
+
+  Add DurableObjectWebSocket.installKeepalive with the exact effect-cf:ping / effect-cf:pong text protocol. RPC Ping/Pong auto-response now stays enabled during pending requests, so keepalives never wake the object. After eviction, lost ordinary RPCs reset on the next application message; clients should use operation deadlines to recover lost work. See the [wakeup migration guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/durable-object-wakeups.md) for migration and recovery details.
+
 ## 0.50.0
 
 ### Minor Changes

package/README.md

@@ -12,6 +12,8 @@ See the [runtime performance guide](https://github.com/danieljvdm/effect-cf/blob
 
 For typed WebSocket RPC clients whose connection lifetime is owned by an Effect layer, see the [WebSocket RPC guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/websocket-rpc.md).
 
+Durable Object alarms bound unchanged retries and self-rearms, and hibernating sockets handle keepalives without waking the object. See the [wakeup and migration guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/durable-object-wakeups.md).
+
 `DurableObjectContainer.layer` adds native `ctx.container` control to `DurableObject.make`: runtime image selection, command execution, filesystem snapshots, networking, and idle timeouts. See the [container guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/containers.md) for setup and migration from the legacy Container and Sandbox classes.
 
 ## Worker

package/dist/DurableObjectAlarm.d.mts

@@ -7,9 +7,38 @@ import * as Layer from "effect/Layer";
 import * as Duration from "effect/Duration";
 import * as DateTime from "effect/DateTime";
 declare namespace DurableObjectAlarm_d_exports {
-  export { AlarmDefinitionConfig, AlarmDefinitionEntry, AlarmDefinitionPayload, AlarmDefinitions, AlarmFailurePolicy, AlarmPayload, AlarmPayloadSchema, AlarmRef, AlarmRegistration, AlarmRetryPolicy, AlarmScheduler, AlarmService, AlarmTagClass, AlarmTransaction, DefinedAlarmEvent, DefinedAlarmHandlers, DefinedAlarmScheduler, DefinedAlarmTransaction, DefinedScheduleAlarmInput, DurableObjectAlarm, DurableObjectAlarmError, DurableObjectAlarmEvent, InvalidAlarmPayloadError, InvalidAlarmRefError, InvalidProcessDueAlarmsOptionsError, InvalidRepeatEveryError, ProcessDueAlarmsFailure, ProcessDueAlarmsFailureAction, ProcessDueAlarmsHandler, ProcessDueAlarmsMode, ProcessDueAlarmsOptions, ProcessDueAlarmsResult, ScheduleAlarmInput, StoredAlarmDecodeError, Tag, define, processDue };
-}
+  export { AlarmDefinitionConfig, AlarmDefinitionEntry, AlarmDefinitionPayload, AlarmDefinitions, AlarmFailurePolicy, AlarmParked, AlarmPayload, AlarmPayloadSchema, AlarmRef, AlarmRegistration, AlarmReporter, AlarmRetryPolicy, AlarmScheduler, AlarmService, AlarmStatus, AlarmTagClass, AlarmTransaction, DEFAULT_MIN_REPEAT_INTERVAL_MS, DefinedAlarmEvent, DefinedAlarmHandlers, DefinedAlarmScheduler, DefinedAlarmTransaction, DefinedScheduleAlarmInput, DurableObjectAlarm, DurableObjectAlarmError, DurableObjectAlarmEvent, InvalidAlarmPayloadError, InvalidAlarmRefError, InvalidProcessDueAlarmsOptionsError, InvalidRepeatEveryError, InvalidScheduleConfigurationError, MIN_REPEAT_INTERVAL_MS, MIN_RETRY_DELAY_MS, PARKED_RETRY_DELAY_MS, ProcessDueAlarmsFailure, ProcessDueAlarmsFailureAction, ProcessDueAlarmsHandler, ProcessDueAlarmsOptions, ProcessDueAlarmsResult, ScheduleAlarmInput, ScheduleConfiguration, StoredAlarmDecodeError, Tag, UNCHANGED_ATTEMPT_BUDGET, define, processDue };
+}
+declare const MIN_RETRY_DELAY_MS = 1000;
+/** Default unchanged-attempt budget. */
+declare const UNCHANGED_ATTEMPT_BUDGET = 8;
+/** Minimum and default parked recovery interval. */
+declare const PARKED_RETRY_DELAY_MS = 3600000;
+/** Absolute product repeat floor. */
+declare const MIN_REPEAT_INTERVAL_MS = 1000;
+/** Default product schedule floor. Never use repeats to poll state. */
+declare const DEFAULT_MIN_REPEAT_INTERVAL_MS = 60000;
+interface ScheduleConfiguration {
+  /** Retry floor, at least one second. Defaults to one second. */
+  readonly minimumRetryDelay?: Duration.Input;
+  /** Positive safe integer. Defaults to eight unchanged attempts. */
+  readonly unchangedAttemptBudget?: number;
+  /** Recovery interval, at least one hour and the retry floor. Defaults to one hour. */
+  readonly parkedRetryDelay?: Duration.Input;
+  /** Product repeat floor, at least one second. Defaults to one minute. */
+  readonly minimumRepeatInterval?: Duration.Input;
+}
+/** Optional policy overrides. Provide with Layer.succeed in the Durable Object's application layer. */
+declare const ScheduleConfiguration: Context.Reference<ScheduleConfiguration>;
 type AlarmPayload = S.Json;
+/** Content-free: no alarm identifiers, payload, error text or consumer state. */
+declare const AlarmParked: S.TaggedStruct<"AlarmParked", {
+  readonly attempts: S.Int;
+  readonly retryAt: S.DateTimeUtc;
+}>;
+type AlarmParked = typeof AlarmParked.Type;
+/** Install with Layer.succeed / Effect.provideService. Reporting cannot undo a committed guard. */
+declare const AlarmReporter: Context.Reference<(event: AlarmParked) => Effect.Effect<void>>;
 declare const InvalidAlarmRefError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "InvalidAlarmRefError";
 } & Readonly<A>;
@@ -42,6 +71,14 @@ declare class InvalidProcessDueAlarmsOptionsError extends InvalidProcessDueAlarm
 }> {
   get message(): string;
 }
+declare const InvalidScheduleConfigurationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "InvalidScheduleConfigurationError";
+} & Readonly<A>;
+declare class InvalidScheduleConfigurationError extends InvalidScheduleConfigurationError_base<{
+  readonly cause: unknown;
+}> {
+  get message(): string;
+}
 declare const StoredAlarmDecodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "StoredAlarmDecodeError";
 } & Readonly<A>;
@@ -51,7 +88,7 @@ declare class StoredAlarmDecodeError extends StoredAlarmDecodeError_base<{
 }> {
   get message(): string;
 }
-type DurableObjectAlarmError = InvalidAlarmPayloadError | InvalidAlarmRefError | InvalidProcessDueAlarmsOptionsError | InvalidRepeatEveryError | StorageOperationError | StoredAlarmDecodeError;
+type DurableObjectAlarmError = InvalidAlarmPayloadError | InvalidAlarmRefError | InvalidProcessDueAlarmsOptionsError | InvalidRepeatEveryError | InvalidScheduleConfigurationError | StorageOperationError | StoredAlarmDecodeError;
 declare const DurableObjectAlarmEvent: S.TaggedUnion<{
   readonly AlarmDue: S.TaggedStruct<"AlarmDue", {
     readonly id: S.NonEmptyString;
@@ -66,13 +103,17 @@ type AlarmRef<Tag extends string = string> = {
   readonly id: string;
   readonly tag: Tag;
 };
-/** Reusing `{tag, id}` replaces an alarm. Repeats run after success, never as fixed-cadence catch-up. */
+/**
+ * Arm a logical deadline. External enrollment is progress; handler self-rearms consume a budget.
+ * Reusing `{tag, id}` replaces an alarm. Product repeats use the configured floor and run after completion.
+ */
 type ScheduleAlarmInput<Tag extends string = string> = AlarmRef<Tag> & {
   readonly payload: AlarmPayload;
   readonly repeatEvery?: Duration.Input;
   readonly runAt: DateTime.Utc;
+  /** Optional monotonic source cursor. Only a strictly increasing cursor resets a live budget. */
+  readonly progress?: number;
 };
-type ProcessDueAlarmsMode = "isolated" | "ordered";
 interface ProcessDueAlarmsFailure {
   readonly cause: unknown;
   readonly event?: DurableObjectAlarmEvent;
@@ -83,10 +124,9 @@ interface ProcessDueAlarmsFailure {
 interface ProcessDueAlarmsResult {
   readonly failed: readonly ProcessDueAlarmsFailure[];
   readonly handled: readonly DurableObjectAlarmEvent[];
+  readonly parked: readonly AlarmParked[];
 }
-type ProcessDueAlarmsFailureAction = "ordered" | "retry" | "skip-and-advance-repeat" | {
-  readonly mode: "ordered";
-} | {
+type ProcessDueAlarmsFailureAction = "retry" | "skip-and-advance-repeat" | {
   readonly mode: "retry";
   readonly retryFailedAfter?: Duration.Input;
 } | {
@@ -94,8 +134,6 @@ type ProcessDueAlarmsFailureAction = "ordered" | "retry" | "skip-and-advance-rep
 };
 interface ProcessDueAlarmsOptions<OnFailureR = never, OnFailureE = never> {
   readonly limit?: number;
-  /** `isolated` retries only the failed row; `ordered` stops before later rows. */
-  readonly mode?: ProcessDueAlarmsMode;
   readonly onFailure?: (failure: ProcessDueAlarmsFailure) => Effect.Effect<ProcessDueAlarmsFailureAction | void, OnFailureE, OnFailureR>;
   readonly retryFailedAfter?: Duration.Input;
 }
@@ -104,7 +142,13 @@ type ProcessDueAlarmsHandler<R = never, E = never> = (event: DurableObjectAlarmE
  * Alarm mutations owned by one transaction callback. Run them in the callback's
  * fiber; forked work and use after the callback ends fail with StorageOperationError.
  */
-type AlarmTransaction = Pick<AlarmScheduler, "scheduleAlarm" | "cancelAlarm">;
+type AlarmTransaction = Pick<AlarmScheduler, "scheduleAlarm" | "scheduleAlarmEarlier" | "cancelAlarm">;
+interface AlarmStatus {
+  readonly attempts: number;
+  readonly parked: boolean;
+  readonly runAt: DateTime.Utc;
+  readonly retryAt: DateTime.Utc | undefined;
+}
 /** Own `storage.setAlarm()` exclusively: a Durable Object has one platform alarm timestamp. */
 type AlarmScheduler = {
   /**
@@ -121,14 +165,21 @@ type AlarmScheduler = {
    */
   readonly transaction: <A, E, R>(closure: (alarms: AlarmTransaction) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StorageOperationError, R>;
   readonly cancelAlarm: (input: AlarmRef) => Effect.Effect<void, InvalidAlarmRefError | StorageOperationError>;
-  /** Acknowledge after handling. Conditional writes preserve handler replacements; alarms are at-least-once. */
+  /** Inspect retained work, including hourly recovery deadlines. */
+  readonly getAlarmStatus: (input: AlarmRef) => Effect.Effect<AlarmStatus | undefined, InvalidAlarmRefError | StorageOperationError>;
+  /**
+   * Dispatch by effective wake deadline, then storage key. Failures retry independently.
+   * Conditional acknowledgements preserve handler replacements; alarms are at-least-once.
+   */
   readonly processDueAlarms: <R = never, E = never, OnFailureR = never, OnFailureE = never>(handle: ProcessDueAlarmsHandler<R, E>, options?: ProcessDueAlarmsOptions<OnFailureR, OnFailureE>) => Effect.Effect<ProcessDueAlarmsResult, E | OnFailureE | DurableObjectAlarmError, R | OnFailureR>;
   /** A failed platform setAlarm rolls back the logical schedule in the same transaction. */
-  readonly scheduleAlarm: (input: ScheduleAlarmInput) => Effect.Effect<void, InvalidAlarmPayloadError | InvalidAlarmRefError | InvalidRepeatEveryError | StorageOperationError>;
+  readonly scheduleAlarm: (input: ScheduleAlarmInput) => Effect.Effect<void, InvalidAlarmPayloadError | InvalidAlarmRefError | InvalidRepeatEveryError | InvalidScheduleConfigurationError | StorageOperationError>;
+  /** Atomically min-merge a logical deadline. Preserves an earlier alarm's payload and repeat. */
+  readonly scheduleAlarmEarlier: AlarmScheduler["scheduleAlarm"];
 };
 declare const processDue: <R = never, E = never, OnFailureR = never, OnFailureE = never>(handle: ProcessDueAlarmsHandler<R, E>, options?: ProcessDueAlarmsOptions<OnFailureR, OnFailureE>) => Effect.Effect<ProcessDueAlarmsResult, E | OnFailureE | DurableObjectAlarmError, OnFailureR | R | DurableObjectAlarm>;
 type AlarmPayloadSchema = S.Codec<any, any, never, never>;
-type AlarmFailurePolicy = "ordered" | "retry" | "skip-and-advance-repeat";
+type AlarmFailurePolicy = "retry" | "skip-and-advance-repeat";
 interface AlarmRetryPolicy {
   readonly initialDelay?: Duration.Input;
 }
@@ -152,6 +203,7 @@ type DefinedScheduleAlarmInput<Definitions extends AlarmDefinitions> = { readonl
 }; }[keyof Definitions & string];
 interface DefinedAlarmTransaction<Definitions extends AlarmDefinitions> {
   readonly scheduleAlarm: (input: DefinedScheduleAlarmInput<Definitions>) => ReturnType<AlarmScheduler["scheduleAlarm"]>;
+  readonly scheduleAlarmEarlier: DefinedAlarmTransaction<Definitions>["scheduleAlarm"];
   readonly cancelAlarm: (input: AlarmRef<keyof Definitions & string>) => ReturnType<AlarmScheduler["cancelAlarm"]>;
 }
 declare const TypedAlarmSchedulerTypeId: unique symbol;
@@ -163,6 +215,7 @@ interface AlarmService {
 }
 interface DefinedAlarmScheduler<Definitions extends AlarmDefinitions> extends DefinedAlarmTransaction<Definitions> {
   readonly [TypedAlarmSchedulerTypeId]: typeof TypedAlarmSchedulerTypeId;
+  readonly getAlarmStatus: (input: AlarmRef<keyof Definitions & string>) => ReturnType<AlarmScheduler["getAlarmStatus"]>;
   readonly transaction: <A, E, R>(closure: (alarms: DefinedAlarmTransaction<Definitions>) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StorageOperationError, R>;
 }
 /** Registers a dispatcher and the service authorized to schedule its alarms. */
@@ -184,4 +237,4 @@ declare class DurableObjectAlarm extends DurableObjectAlarm_base {
   static readonly layer: Layer.Layer<DurableObjectAlarm, never, DurableObjectState>;
 }
 //#endregion
-export { AlarmDefinitionConfig, AlarmDefinitionEntry, AlarmDefinitionPayload, AlarmDefinitions, AlarmFailurePolicy, AlarmPayload, AlarmPayloadSchema, AlarmRef, AlarmRegistration, AlarmRetryPolicy, AlarmScheduler, AlarmService, AlarmTagClass, AlarmTransaction, DefinedAlarmEvent, DefinedAlarmHandlers, DefinedAlarmScheduler, DefinedAlarmTransaction, DefinedScheduleAlarmInput, DurableObjectAlarm, DurableObjectAlarmError, DurableObjectAlarmEvent, DurableObjectAlarm_d_exports, InvalidAlarmPayloadError, InvalidAlarmRefError, InvalidProcessDueAlarmsOptionsError, InvalidRepeatEveryError, ProcessDueAlarmsFailure, ProcessDueAlarmsFailureAction, ProcessDueAlarmsHandler, ProcessDueAlarmsMode, ProcessDueAlarmsOptions, ProcessDueAlarmsResult, ScheduleAlarmInput, StoredAlarmDecodeError, Tag, define, processDue };
+export { AlarmDefinitionConfig, AlarmDefinitionEntry, AlarmDefinitionPayload, AlarmDefinitions, AlarmFailurePolicy, AlarmParked, AlarmPayload, AlarmPayloadSchema, AlarmRef, AlarmRegistration, AlarmReporter, AlarmRetryPolicy, AlarmScheduler, AlarmService, AlarmStatus, AlarmTagClass, AlarmTransaction, DEFAULT_MIN_REPEAT_INTERVAL_MS, DefinedAlarmEvent, DefinedAlarmHandlers, DefinedAlarmScheduler, DefinedAlarmTransaction, DefinedScheduleAlarmInput, DurableObjectAlarm, DurableObjectAlarmError, DurableObjectAlarmEvent, DurableObjectAlarm_d_exports, InvalidAlarmPayloadError, InvalidAlarmRefError, InvalidProcessDueAlarmsOptionsError, InvalidRepeatEveryError, InvalidScheduleConfigurationError, MIN_REPEAT_INTERVAL_MS, MIN_RETRY_DELAY_MS, PARKED_RETRY_DELAY_MS, ProcessDueAlarmsFailure, ProcessDueAlarmsFailureAction, ProcessDueAlarmsHandler, ProcessDueAlarmsOptions, ProcessDueAlarmsResult, ScheduleAlarmInput, ScheduleConfiguration, StoredAlarmDecodeError, Tag, UNCHANGED_ATTEMPT_BUDGET, define, processDue };