effect-browser 0.3.0-beta.14 → 0.3.0-beta.15

package/src/Supervisor.ts

@@ -21,6 +21,7 @@
 import {
   Cause,
   Clock,
+  Context,
   DateTime,
   Deferred,
   Duration,
@@ -96,12 +97,23 @@ export interface Opened<A = void> {
 export interface Admission {
   readonly number: number;
   /**
-   * The preceding generation's release once it stops serving. Undefined on the first open and
-   * while a nonexclusive rotation keeps it serving; checked again before each retry.
+   * Every earlier session that stopped serving, including failed attempts and older drains.
+   * Waits for all pending releases; an Unconfirmed end remains visible to later attempts.
+   * Undefined before any release. A still-serving nonexclusive predecessor is excluded.
    */
   readonly after: Effect.Effect<Lifecycle.Released> | undefined;
 }
 
+/**
+ * Optional service supplied during `open`. Providers report failed-attempt cleanup here before
+ * their scope closes; successful generations instead return `Opened.release`. Reporting does
+ * not release resources or replace the original acquisition failure.
+ */
+export class Releasing extends Context.Service<
+  Releasing,
+  { readonly released: (outcome: Lifecycle.Released) => Effect.Effect<void> }
+>()("effect-browser/Supervisor/Releasing") {}
+
 export interface Options<E, R, A = void> {
   /** Opens one generation in the scope it is given. */
   readonly open: Effect.Effect<Opened<A>, E, R>;
@@ -186,9 +198,9 @@ interface Held<A> {
 }
 
 type State<A> = Lifecycle.State<Held<A>, Hold>;
-type Apply<A> = (
-  input: Lifecycle.Input<Held<A>, Hold>,
-) => Effect.Effect<Lifecycle.Step<Held<A>, Hold>>;
+type Input<A> = Lifecycle.Input<Held<A>, Hold>;
+type Step<A> = Lifecycle.Step<Held<A>, Hold>;
+type Apply<A> = (input: Input<A>) => Effect.Effect<Step<A>>;
 
 const superseded = (generation: number, { reason, revokeAt }: Lifecycle.Draining) =>
   new Superseded({ generation, reason, revokeAt });
@@ -201,15 +213,6 @@ const describe = (cause: Cause.Cause<unknown>) => {
   return Predicate.isError(error) ? error.message : String(error);
 };
 
-const unavailable = (
-  resolution: Extract<Lifecycle.Resolution<unknown>, { readonly _tag: "Unavailable" }>,
-) =>
-  new Unavailable({
-    reason: resolution.reason,
-    detail: resolution.detail,
-    cause: resolution.cause,
-  });
-
 const timedOut = () =>
   new Unavailable({ reason: "opening", detail: "no generation opened within the wait" });
 
@@ -234,7 +237,7 @@ const waitFor = <A, H>(
   const result = (resolution: Lifecycle.Resolution<A>) =>
     resolution._tag === "Serve"
       ? Effect.succeed(resolution.live)
-      : Effect.fail(unavailable(resolution));
+      : Effect.fail(new Unavailable(resolution));
 
   return Effect.suspend(() => {
     const current = Lifecycle.resolve(state.value, target);
@@ -277,20 +280,19 @@ const leasing = <A>(
   now: () => number,
   clock: Clock.Clock,
 ) => {
-  const borrow = (hold: Hold, wait: Duration.Duration) =>
-    Effect.gen(function* () {
-      const until = now() + Duration.toMillis(wait);
-
-      for (;;) {
-        const step = yield* apply({ _tag: "Hold", hold });
-
-        if (step.borrowed !== undefined) return step.borrowed;
-        yield* waitFor(state, Duration.millis(Math.max(0, until - now())), clock).pipe(
-          Effect.interruptible,
-        );
-        if (now() >= until) return yield* timedOut();
-      }
-    });
+  const borrow = Effect.fnUntraced(function* (hold: Hold, wait: Duration.Duration) {
+    const until = now() + Duration.toMillis(wait);
+
+    for (;;) {
+      const step = yield* apply({ _tag: "Hold", hold });
+
+      if (step.borrowed !== undefined) return step.borrowed;
+      yield* waitFor(state, Duration.millis(Math.max(0, until - now())), clock).pipe(
+        Effect.interruptible,
+      );
+      if (now() >= until) return yield* timedOut();
+    }
+  });
 
   const leaseOf = (live: Lifecycle.Live<Held<A>>): Lease<A> => ({
     generation: live.number,
@@ -373,11 +375,6 @@ const acquireGeneration = <A, E, R>(
     ),
   );
 
-const changedUntil = <A>(
-  state: SubscriptionRef.SubscriptionRef<State<A>>,
-  predicate: (current: State<A>) => boolean,
-) => SubscriptionRef.changes(state).pipe(Stream.filter(predicate), Stream.runHead, Effect.asVoid);
-
 const watchGeneration = <A>(
   live: Lifecycle.Live<Held<A>>,
   rotateBefore: Duration.Duration | undefined,
@@ -400,59 +397,61 @@ const watchGeneration = <A>(
 };
 
 // After revocation, retained resources and use finalizers let go before the provider.
-const releaseGeneration = <A>(
+const releaseGeneration = Effect.fnUntraced(function* <A>(
   command: Extract<Lifecycle.Command<Held<A>>, { readonly _tag: "Release" | "Leave" }>,
   state: SubscriptionRef.SubscriptionRef<State<A>>,
   apply: Apply<A>,
-) =>
-  Effect.gen(function* () {
-    const { live } = command;
-    const holds = Lifecycle.lookup(state.value, live.number)?.holds ?? [];
-
-    const cleaned = yield* Effect.forEach(
-      holds,
-      (hold) =>
-        Effect.exit(hold._tag === "Retained" ? Scope.close(hold.scope, Exit.void) : Effect.void),
-      { concurrency: 8 },
-    );
+) {
+  const { live } = command;
+
+  const cleaned = yield* Effect.forEach(
+    Lifecycle.lookup(state.value, live.number)?.holds ?? [],
+    (hold) =>
+      Effect.exit(hold._tag === "Retained" ? Scope.close(hold.scope, Exit.void) : Effect.void),
+    { concurrency: 8 },
+  );
 
-    yield* changedUntil(
-      state,
-      (current) => (Lifecycle.lookup(current, live.number)?.holds.size ?? 0) === 0,
-    );
+  yield* SubscriptionRef.changes(state).pipe(
+    Stream.filter((current) => (Lifecycle.lookup(current, live.number)?.holds.size ?? 0) === 0),
+    Stream.runHead,
+  );
 
-    const released =
-      command._tag === "Leave"
-        ? undefined
-        : yield* (live.value.opened.release ?? Effect.succeed(new Lifecycle.Settled())).pipe(
-            Effect.catchCause((cause) =>
-              Effect.succeed(
-                new Lifecycle.Unconfirmed({ detail: `the release failed: ${describe(cause)}` }),
-              ),
+  const released =
+    command._tag === "Leave"
+      ? undefined
+      : yield* (live.value.opened.release ?? Effect.succeed(new Lifecycle.Settled())).pipe(
+          Effect.catchCause((cause) =>
+            Effect.succeed(
+              new Lifecycle.Unconfirmed({ detail: `the release failed: ${describe(cause)}` }),
             ),
-          );
+          ),
+        );
 
-    const closed = yield* Effect.exit(Scope.close(live.value.scope, Exit.void));
+  const closed = yield* Effect.exit(Scope.close(live.value.scope, Exit.void));
 
-    yield* apply({ _tag: "Released", number: live.number, released });
-    if (released !== undefined) yield* Deferred.succeed(live.value.released, released);
-    yield* Exit.asVoidAll([...cleaned, closed]);
-  });
+  yield* apply({ _tag: "Released", number: live.number, released });
+  if (released !== undefined) yield* Deferred.succeed(live.value.released, released);
+  yield* Exit.asVoidAll([...cleaned, closed]);
+});
 
-const openedInput = <A, E>(
-  number: number,
-  exit: Exit.Exit<Held<A>, E>,
-): Lifecycle.Input<Held<A>, Hold> =>
-  Exit.isSuccess(exit)
-    ? { _tag: "Opened", live: { number, value: exit.value } }
-    : Cause.hasInterruptsOnly(exit.cause)
-      ? { _tag: "Abandoned", number }
-      : { _tag: "Failed", number, detail: describe(exit.cause), cause: Cause.squash(exit.cause) };
-
-const admissionAfter = <A>(previous: Lifecycle.Live<Held<A>> | undefined, state: State<A>) =>
-  previous === undefined || (state._tag !== "Retired" && state.serving?.number === previous.number)
+const admissionAfter = <A>(state: State<A>) => {
+  const released = state.released;
+
+  const pending = [...state.draining.values()]
+    .filter((drain) => drain._tag !== "Leaving")
+    .map(({ live }) => live.value.released);
+
+  return pending.length === 0 && released === undefined
     ? undefined
-    : Deferred.await(previous.value.released);
+    : Effect.gen(function* () {
+        let outcome = released;
+
+        for (const release of pending)
+          outcome = Lifecycle.combine(outcome, yield* Deferred.await(release));
+
+        return outcome ?? new Lifecycle.Settled();
+      });
+};
 
 const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
   options: MakeOptions<E, R, A>,
@@ -462,7 +461,6 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
   const context = yield* Effect.context<Exclude<R, Scope.Scope>>();
   const own = yield* Scope.fork(yield* Effect.scope);
   const exclusive = options.exclusive ?? false;
-  const definite = options.definite ?? (() => false);
 
   const reopen: Schedule.Schedule<unknown, E> =
     options.reopen ??
@@ -486,113 +484,116 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
   const runOpen = yield* FiberHandle.runtime(opening)();
   const runRelease = yield* FiberMap.runtime(releases)();
 
-  const apply = (
-    input: Lifecycle.Input<Held<A | void>, Hold>,
-  ): Effect.Effect<Lifecycle.Step<Held<A | void>, Hold>> =>
-    applying
-      .withPermit(
-        Effect.gen(function* () {
-          const current = state.value;
-          const step = Lifecycle.transition(current, input, exclusive, now(), handover);
+  const apply: Apply<A | void> = Effect.fnUntraced(
+    function* (input: Input<A | void>) {
+      const current = state.value;
+      const step = Lifecycle.transition(current, input, exclusive, now(), handover);
 
-          if (step.state !== current) yield* SubscriptionRef.set(state, step.state);
-          yield* perform(step);
+      if (step.state !== current) yield* SubscriptionRef.set(state, step.state);
+      yield* perform(step);
+
+      return step;
+    },
+    (effect) => applying.withPermit(effect),
+    Effect.uninterruptible,
+    Effect.provideService(Clock.Clock, clock),
+  );
 
-          return step;
+  const perform = Effect.fnUntraced(function* (step: Step<A | void>): Effect.fn.Return<void> {
+    for (const [number, generation] of step.events)
+      PubSub.publishUnsafe(events, [
+        new Generation({
+          number,
+          at: clock.currentTimeMillisUnsafe(),
+          hostTime: now(),
+          state: generation,
         }),
-      )
-      .pipe(Effect.uninterruptible, Effect.provideService(Clock.Clock, clock));
-
-  const perform = (step: Lifecycle.Step<Held<A | void>, Hold>): Effect.Effect<void> =>
-    Effect.gen(function* () {
-      for (const [number, generation] of step.events)
-        PubSub.publishUnsafe(events, [
-          new Generation({
-            number,
-            at: clock.currentTimeMillisUnsafe(),
-            hostTime: now(),
-            state: generation,
-          }),
-        ]);
-      for (const command of step.commands)
-        switch (command._tag) {
-          case "Open":
-            runOpen(openGeneration(command.number, command.after));
-            break;
-          case "Watch":
-            yield* Effect.forkIn(
-              Effect.provideContext(watchGeneration(command.live, rotateBefore, apply), context),
-              command.live.value.scope,
-            );
-            break;
-          case "Drain": {
-            const ending = superseded(command.live.number, command.ending);
-
-            yield* Deferred.succeed(command.live.value.ending, ending);
-            yield* Effect.forkIn(
-              until(ending.revokeAt, now).pipe(
-                Effect.andThen(
-                  Effect.suspend(() => apply({ _tag: "Revoke", number: command.live.number })),
-                ),
+      ]);
+    for (const command of step.commands)
+      switch (command._tag) {
+        case "Open":
+          runOpen(openGeneration(command.number));
+          break;
+        case "Watch":
+          yield* Effect.forkIn(
+            Effect.provideContext(watchGeneration(command.live, rotateBefore, apply), context),
+            command.live.value.scope,
+          );
+          break;
+        case "Drain": {
+          const ending = superseded(command.live.number, command.ending);
+
+          yield* Deferred.succeed(command.live.value.ending, ending);
+          yield* Effect.forkIn(
+            until(ending.revokeAt, now).pipe(
+              Effect.andThen(
+                Effect.suspend(() => apply({ _tag: "Revoke", number: command.live.number })),
               ),
-              command.live.value.scope,
-            );
-            break;
-          }
-          case "Release":
-          case "Leave":
-            yield* Deferred.succeed(
-              command.live.value.revoked,
-              superseded(command.live.number, command.ending),
-            );
-            runRelease(command.live.number, releaseGeneration(command, state, apply));
-            break;
+            ),
+            command.live.value.scope,
+          );
+          break;
         }
-    });
-
-  const openGeneration = (number: number, previous: Lifecycle.Live<Held<A | void>> | undefined) => {
-    const after = previous === undefined ? undefined : Deferred.await(previous.value.released);
+        case "Release":
+        case "Leave":
+          yield* Deferred.succeed(
+            command.live.value.revoked,
+            superseded(command.live.number, command.ending),
+          );
+          runRelease(command.live.number, releaseGeneration(command, state, apply));
+          break;
+      }
+  });
 
+  const openGeneration = (number: number) => {
     const openOnce = acquireGeneration(
-      Effect.suspend(
-        () =>
-          options.admit?.({ number, after: admissionAfter(previous, state.value) }) ?? Effect.void,
-      ).pipe(Effect.andThen(options.open)),
+      Effect.gen(function* () {
+        const after = admissionAfter(state.value);
+
+        if (exclusive && after !== undefined) yield* after;
+        yield* options.admit?.({ number, after }) ?? Effect.void;
+
+        return yield* options.open.pipe(
+          Effect.provideService(Releasing, {
+            released: (released) =>
+              apply({ _tag: "AttemptReleased", released }).pipe(Effect.asVoid),
+          }),
+        );
+      }),
       own,
     ).pipe(Effect.provideContext(context));
 
     return Effect.uninterruptibleMask((restore) =>
       restore(
-        (exclusive && after !== undefined ? after : Effect.void).pipe(
-          Effect.andThen(
-            Effect.retry(openOnce, { schedule: reopen, while: (error) => !definite(error) }),
-          ),
-        ),
+        Effect.retry(openOnce, {
+          schedule: reopen,
+          while: (error) => !options.definite?.(error),
+        }),
       ).pipe(
         Effect.exit,
-        Effect.flatMap((exit) => apply(openedInput(number, exit))),
+        Effect.flatMap((exit) => {
+          if (Exit.isSuccess(exit))
+            return apply({ _tag: "Opened", live: { number, value: exit.value } });
+          const cause = exit.cause;
+
+          return apply(
+            Cause.hasInterruptsOnly(cause)
+              ? { _tag: "Abandoned", number }
+              : { _tag: "Failed", number, detail: describe(cause), cause: Cause.squash(cause) },
+          );
+        }),
       ),
     );
   };
 
-  const use = leasing(state, apply, waitTimeout, now, clock);
-
   const end = yield* Effect.cached(PubSub.publish(events, Exit.void));
 
-  const stop = (input: Lifecycle.Input<Held<A | void>, Hold>) =>
-    apply(input).pipe(
-      Effect.andThen(FiberHandle.clear(opening)),
-      Effect.andThen(FiberMap.awaitEmpty(releases)),
-      Effect.andThen(
-        Effect.suspend(() =>
-          Deferred.isDone(releases.deferred).pipe(
-            Effect.flatMap((failed) => (failed ? FiberMap.join(releases) : Effect.void)),
-          ),
-        ),
-      ),
-      Effect.ensuring(end),
-      Effect.asVoid,
-    );
+  const stop = Effect.fnUntraced(function* (input: Input<A | void>) {
+    yield* apply(input);
+    yield* FiberHandle.clear(opening);
+    yield* FiberMap.awaitEmpty(releases);
+    if (yield* Deferred.isDone(releases.deferred)) yield* FiberMap.join(releases);
+  }, Effect.ensuring(end));
 
   const retire = yield* Effect.cached(stop({ _tag: "Retire" }));
 
@@ -601,7 +602,7 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
 
   return {
     browser: Effect.map(waitFor(state, waitTimeout, clock), (live) => live.value.opened.browser),
-    use,
+    use: leasing(state, apply, waitTimeout, now, clock),
     states: Stream.fromPubSubTake(events),
     rotate: apply({ _tag: "Rotate" }).pipe(
       Effect.flatMap(({ reply }) =>

package/src/internal/supervisor/lifecycle.ts

@@ -104,12 +104,13 @@ export type State<A, H = unknown> = (
   | { readonly _tag: "Retired" }
 ) & {
   readonly draining: ReadonlyMap<number, Drain<A, H>>;
-  /** One bounded predecessor survives release and failed acquisitions for admission. */
-  readonly latest: Live<A> | undefined;
+  /** Retain the first unconfirmed end, otherwise the latest settled end, without its resources. */
+  readonly released?: Released | undefined;
 };
 
 export type Input<A, H = unknown> =
   | { readonly _tag: "Opened"; readonly live: Live<A> }
+  | { readonly _tag: "AttemptReleased"; readonly released: Released }
   | {
       readonly _tag: "Failed";
       readonly number: number;
@@ -140,7 +141,7 @@ export type Input<A, H = unknown> =
     };
 
 export type Command<A> =
-  | { readonly _tag: "Open"; readonly number: number; readonly after: Live<A> | undefined }
+  | { readonly _tag: "Open"; readonly number: number }
   | { readonly _tag: "Watch"; readonly live: Live<A> }
   /** Signal ending and arrange revocation. Repeated only when loss/retirement accelerates it. */
   | { readonly _tag: "Drain"; readonly live: Live<A>; readonly ending: Draining }
@@ -157,9 +158,9 @@ export interface Step<A, H = unknown> {
 }
 
 export const start = <A, H = unknown>(): Step<A, H> => ({
-  state: { _tag: "Opening", number: 1, serving: undefined, draining: new Map(), latest: undefined },
+  state: { _tag: "Opening", number: 1, serving: undefined, draining: new Map() },
   events: [[1, new Opening()]],
-  commands: [{ _tag: "Open", number: 1, after: undefined }],
+  commands: [{ _tag: "Open", number: 1 }],
 });
 
 const servingOf = <A, H>(state: State<A, H>) =>
@@ -270,8 +271,6 @@ const next = <A, H>(change: Change<A, H>, number: number, reopen: boolean) => {
   const { exclusive } = change;
   const current = servingOf(change.state);
 
-  const after = change.state.latest;
-
   if (current !== undefined && (reopen || exclusive))
     end(change, current, reopen ? "lost" : "rotated");
   change.state = {
@@ -279,10 +278,10 @@ const next = <A, H>(change: Change<A, H>, number: number, reopen: boolean) => {
     number,
     serving: reopen || exclusive ? undefined : current,
     draining: change.state.draining,
-    latest: after,
+    released: change.state.released,
   };
   change.events.push([number, reopen ? new Reopening() : new Opening()]);
-  change.commands.push({ _tag: "Open", number, after });
+  change.commands.push({ _tag: "Open", number });
 };
 
 const lost = <A, H>(
@@ -346,7 +345,7 @@ export const transition = <A, H = unknown>(
           _tag: "Open",
           serving: live,
           draining: change.state.draining,
-          latest: input.live,
+          released: change.state.released,
         };
       }
       break;
@@ -362,6 +361,9 @@ export const transition = <A, H = unknown>(
     case "Abandoned":
       change.events.push([input.number, new Closed({})]);
       break;
+    case "AttemptReleased":
+      change.state = { ...state, released: combine(state.released, input.released) };
+      break;
     case "Released": {
       const drain = state.draining.get(input.number);
 
@@ -369,7 +371,7 @@ export const transition = <A, H = unknown>(
       const draining = new Map(state.draining);
 
       draining.delete(input.number);
-      change.state = { ...state, draining };
+      change.state = { ...state, draining, released: combine(state.released, input.released) };
       change.events.push([
         input.number,
         input.released === undefined ? new Kept() : new Closed({ released: input.released }),
@@ -397,12 +399,20 @@ export const transition = <A, H = unknown>(
       if (state._tag === "Retired") break;
       for (const number of state.draining.keys()) revoke(change, number, "retired");
       if (state.serving !== undefined) end(change, state.serving, "retired", input._tag === "Keep");
-      change.state = { _tag: "Retired", draining: change.state.draining, latest: undefined };
+      change.state = {
+        _tag: "Retired",
+        draining: change.state.draining,
+        released: change.state.released,
+      };
   }
 
   return change;
 };
 
+/** Later confirmations cannot establish that an earlier unconfirmed session ended. */
+export const combine = (before: Released | undefined, next: Released | undefined) =>
+  before?._tag === "Unconfirmed" ? before : (next ?? before);
+
 export type Resolution<A> =
   | { readonly _tag: "Serve"; readonly live: Live<A> }
   | {