import * as Cause from "effect/Cause"; import * as Effect from "effect/Effect"; import * as Fiber from "effect/Fiber"; import * as Formatter from "effect/Formatter"; import * as Logger from "effect/Logger"; import type * as LogLevel from "effect/LogLevel"; import * as Predicate from "effect/Predicate"; 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 = new Set( Event.members.map((member) => member.fields.type.literal), ); /** * First human-readable line of a lifecycle failure, for the per-resource * `fail` status event. The full cause is still aggregated and raised when * the whole run settles — this exists so a failed row explains itself the * moment it fails instead of only after every sibling has finished. * `undefined` for interrupt-only causes (nothing failed, the run was * cancelled). */ export const failureMessage = (cause: Cause.Cause): string | undefined => { for (const reason of cause.reasons) { const error = Cause.isFailReason(reason) ? reason.error : Cause.isDieReason(reason) ? reason.defect : undefined; if (error === undefined) continue; const tag = Predicate.hasProperty(error, "_tag") && typeof error._tag === "string" ? error._tag : undefined; const message = Predicate.hasProperty(error, "message") && typeof error.message === "string" ? error.message : typeof error === "string" ? error : Formatter.format(error); const line = message.split("\n", 1)[0]!; return tag !== undefined && !line.includes(tag) ? `${tag}: ${line}` : line; } return undefined; }; /** 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 => 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): 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> = 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 = (handler: (event: Event) => Effect.Effect) => (effect: Effect.Effect): Effect.Effect => Effect.gen(function* () { const queue = yield* Queue.unbounded(); 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((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)), ); });