import * as Cause from "effect/Cause";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as Logger from "effect/Logger";
import type * as LogLevel from "effect/LogLevel";
import * as Queue from "effect/Queue";
import { CurrentLogAnnotations, MinimumLogLevel } from "effect/References";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import { LogAnnotation } from "./Util/LogAnnotation.ts";
// The engine's typed events: one Schema union discriminated by `type`
// (`domain.subject.verb`), emitted as log records through Effect's logger.
// `onEvent` observes them; every logger (the run log, JSON output) sees them
// too. Time, trace and resource live on the log record, not the event.
const ProviderMode = Schema.Literals(["local", "live"]);
export const ApplyStatus = Schema.Literals([
"attaching",
"post-attach",
"pending",
"pre-creating",
"creating",
"creating replacement",
"created",
"updating",
"updated",
"adopting",
"adopted",
"deleting",
"deleted",
"orphaning",
"orphaned",
"replacing",
"replaced",
// Action lifecycle (see `Action`)
"running",
"ran",
"skipped",
"fail",
]);
export type ApplyStatus = typeof ApplyStatus.Type;
/**
* How append-only renderers surface a note (the interactive view treats every
* kind the same): `"status"` is transient spinner text that plain mode folds
* into the settle line's suffix, `"output"` is verbatim tool output streamed
* line by line, and absent is a one-shot informational note.
*/
export const NoteKind = Schema.Literals(["status", "output"]);
export type NoteKind = typeof NoteKind.Type;
/** One binding row on a planned resource. */
export const PlannedBinding = Schema.Struct({
sid: Schema.String,
action: Schema.Literals(["create", "update", "delete", "noop"]),
});
export type PlannedBinding = typeof PlannedBinding.Type;
/** Serializable view of one resource row in a plan. */
export const PlannedResource = Schema.Struct({
fqn: Schema.String,
logicalId: Schema.String,
resourceType: Schema.String,
/** The action the plan decided for this resource. */
action: Schema.Literals(["create", "update", "adopted", "replace", "delete", "orphaned", "noop"]),
/** Binding rows the node carries; empty when the resource has none. */
bindings: Schema.Array(PlannedBinding),
/** Mode the node's provider resolved for; absent for mode-agnostic providers. */
providerMode: Schema.optionalKey(ProviderMode),
/** On mode-switch replacements: the mode the old generation was created with. */
fromProviderMode: Schema.optionalKey(ProviderMode),
});
export type PlannedResource = typeof PlannedResource.Type;
/** Serializable view of one stack-action row in a plan. */
export const PlannedAction = Schema.Struct({
fqn: Schema.String,
logicalId: Schema.String,
actionType: Schema.String,
action: Schema.Literals(["run", "delete", "noop"]),
});
export type PlannedAction = typeof PlannedAction.Type;
/** Phases a stack plan moves through before it is ready. */
export const PlanningPhase = Schema.Literals([
"importing-module",
"resolving-services",
"loading-state",
"computing-plan",
"plan-ready",
]);
export type PlanningPhase = typeof PlanningPhase.Type;
/** A note a provider attached to a resource while applying it. */
export const ResourceAnnotated = Schema.Struct({
type: Schema.Literal("apply.resource.note"),
/** Fully-qualified resource or action name used to target its plan row. */
fqn: Schema.String,
id: Schema.String,
message: Schema.String,
kind: Schema.optionalKey(NoteKind),
});
export type ResourceAnnotated = typeof ResourceAnnotated.Type;
/** A resource or action moved to a new apply status. */
export const ResourceStatusChanged = Schema.Struct({
type: Schema.Literal("apply.resource.status"),
/** Fully-qualified resource or action name used to target its plan row. */
fqn: Schema.String,
/** Logical id, e.g. `"api"`. */
id: Schema.String,
/** e.g. `"Cloudflare.Worker"`. */
resourceType: Schema.String,
status: ApplyStatus,
message: Schema.optionalKey(Schema.String),
/**
* The mode this node's provider was resolved for; absent for mode-agnostic
* providers and for actions.
*/
providerMode: Schema.optionalKey(ProviderMode),
/**
* Set only on mode-switch replacements (local ⇄ live): the mode the OLD
* generation was created with. Always differs from `providerMode`.
*/
fromProviderMode: Schema.optionalKey(ProviderMode),
});
export type ResourceStatusChanged = typeof ResourceStatusChanged.Type;
export type ApplyEvent = ResourceAnnotated | ResourceStatusChanged;
/** Every event the engine and the Alchemist operations emit. */
export const Event = Schema.Union([
/**
* The planning pipeline crossed a work boundary. Carries no display text —
* wording is the renderer's job.
*/
Schema.Struct({ type: Schema.Literal("plan.phase"), phase: PlanningPhase }),
/**
* A resource's diff began. Diffs run concurrently and may read the cloud,
* so pairing starts with completions lets a renderer show what is in flight.
*/
Schema.Struct({
type: Schema.Literal("plan.resource.started"),
fqn: Schema.String,
logicalId: Schema.String,
resourceType: Schema.String,
total: Schema.Number,
}),
/** The planner finished diffing one resource; `completed` of `total` so far. */
Schema.Struct({
type: Schema.Literal("plan.resource.completed"),
...PlannedResource.fields,
completed: Schema.Number,
total: Schema.Number,
}),
/** The planner decided one stack action. */
Schema.Struct({
type: Schema.Literal("plan.action.completed"),
...PlannedAction.fields,
completed: Schema.Number,
total: Schema.Number,
}),
ResourceAnnotated,
ResourceStatusChanged,
/**
* Around a state-store bootstrap or upgrade (e.g. deploying the Cloudflare
* state-store worker on first use); `store` names it.
*/
Schema.Struct({ type: Schema.Literal("state.bootstrap.started"), store: Schema.String }),
Schema.Struct({ type: Schema.Literal("state.bootstrap.completed"), store: Schema.String }),
Schema.Struct({ type: Schema.Literal("provider.configure.started"), provider: Schema.String }),
Schema.Struct({ type: Schema.Literal("provider.configure.completed"), provider: Schema.String }),
Schema.Struct({ type: Schema.Literal("provider.refresh.started"), provider: Schema.String }),
Schema.Struct({ type: Schema.Literal("provider.refresh.completed"), provider: Schema.String }),
Schema.Struct({ type: Schema.Literal("nuke.scan.started"), total: Schema.Number }),
Schema.Struct({ type: Schema.Literal("nuke.scan.provider.started"), provider: Schema.String }),
/** One provider's listing settled: 0 resources and an `error` when it failed. */
Schema.Struct({
type: Schema.Literal("nuke.scan.provider.completed"),
provider: Schema.String,
resources: Schema.Number,
error: Schema.optionalKey(Schema.String),
}),
Schema.Struct({ type: Schema.Literal("nuke.pass.started"), pass: Schema.Number }),
/** `resource` is the deleted object's display name. */
Schema.Struct({
type: Schema.Literal("nuke.resource.deleted"),
provider: Schema.String,
resource: Schema.String,
}),
/** A deletion attempt failed; the run keeps going. */
Schema.Struct({
type: Schema.Literal("nuke.resource.failed"),
provider: Schema.String,
resource: Schema.String,
message: Schema.String,
}),
]);
export type Event = typeof Event.Type;
const knownEventTypes: ReadonlySet<string> = new Set(
Event.members.map((member) => member.fields.type.literal),
);
/** Whether `type` names an event this version knows. */
export const isKnownEventType = (type: string): boolean => knownEventTypes.has(type);
/**
* The level an event is logged at: failures stand out, so a reader filtering
* the run log by level (`select(.level == "error")`) finds them.
*/
const levelOf = (event: Event): LogLevel.Severity =>
event.type === "apply.resource.status" && event.status === "fail"
? "Error"
: event.type === "nuke.resource.failed" ||
(event.type === "nuke.scan.provider.completed" && event.error !== undefined)
? "Warn"
: "Info";
/**
* Emit an event. Events are log records (annotated as events, at Info unless
* they report a failure), so every logger sees them: the run log and
* `--log-format json` carry them and renderers subscribe with
* {@link onEvent}. The pretty console sink skips them, and telemetry does not
* export them.
*/
export const emit = (event: Event): Effect.Effect<void> =>
Effect.logWithLevel(levelOf(event))(event).pipe(
Effect.annotateLogs(LogAnnotation.event, true),
// Events always reach the loggers; each sink applies its own floor
// (the console's `--log-level`), so a quieter minimum never starves a
// renderer or the run log of progress.
Effect.provideService(MinimumLogLevel, "Trace"),
);
/** The event a log record carries, if it is one. */
const eventOf = (options: Logger.Options<unknown>): Event | undefined => {
if (options.fiber.getRef(CurrentLogAnnotations)[LogAnnotation.event] !== true) return undefined;
const message = Array.isArray(options.message) ? options.message[0] : options.message;
// SAFETY: only `emit` sets the event annotation, and it logs an Event.
return message as Event;
};
/**
* {@link emit} bound to the current loggers, for reporting from contexts
* that may no longer carry them (provider callbacks, cached operations), so
* the events still reach the caller's sinks and `onEvent` subscribers.
*/
export const captureEmit: Effect.Effect<(event: Event) => Effect.Effect<void>> = Effect.map(
Logger.CurrentLoggers,
(loggers) => (event) => emit(event).pipe(Effect.provideService(Logger.CurrentLoggers, loggers)),
);
/**
* Observe the events `effect` emits. The handler runs (with the caller's
* services) for each event in order, alongside the loggers already
* installed, and every handler has finished before this returns.
*/
export const onEvent =
<R = never>(handler: (event: Event) => Effect.Effect<void, never, R>) =>
<A, E, R2>(effect: Effect.Effect<A, E, R2>): Effect.Effect<A, E, R | R2> =>
Effect.gen(function* () {
const queue = yield* Queue.unbounded<Event, Cause.Done>();
const consumer = yield* Stream.fromQueue(queue).pipe(
Stream.runForEach(handler),
Effect.forkDetach,
);
// Every event emitted so far is handled before returning.
const drain = Queue.end(queue).pipe(Effect.andThen(Fiber.join(consumer)));
return yield* effect.pipe(
Effect.provide(
Logger.layer(
[
Logger.make<unknown, void>((options) => {
const event = eventOf(options);
if (event !== undefined) Queue.offerUnsafe(queue, event);
}),
],
{ mergeWithExisting: true },
),
),
// `effect` stays on this fiber, so fibers it forks live as long as
// the caller's. A handler that died fails the operation here.
Effect.tap(() => drain),
Effect.tapCause((cause) =>
Cause.hasInterruptsOnly(cause) ? Effect.void : Effect.ignore(drain),
),
// Cancelled: stop handling instead of waiting on a blocked handler.
Effect.onInterrupt(() => Fiber.interrupt(consumer)),
// Whatever the exit, later emits are rejected instead of piling up
// in a queue nothing reads.
Effect.ensuring(Queue.shutdown(queue)),
);
});