Skip to content
3 changes: 3 additions & 0 deletions apps/desktop/src/app/DesktopState.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Ref from "effect/Ref";
import * as SubscriptionRef from "effect/SubscriptionRef";
import type { DatabaseMigrationProgress } from "@t3tools/contracts";

import type { BackendStartupFailure } from "../backend/DesktopBackendManager.ts";

Expand All @@ -20,6 +21,7 @@ export class DesktopState extends Context.Service<
// Set by DesktopUpdates.configure, which runs before the first backend start.
readonly canInstallUpdates: Ref.Ref<boolean>;
readonly primaryBackendStartup: SubscriptionRef.SubscriptionRef<PrimaryBackendStartup>;
readonly databaseMigrationProgress: Ref.Ref<DatabaseMigrationProgress | null>;
}
>()("@t3tools/desktop/app/DesktopState") {}

Expand All @@ -28,6 +30,7 @@ const make = Effect.all({
quitting: Ref.make(false),
canInstallUpdates: Ref.make(false),
primaryBackendStartup: SubscriptionRef.make<PrimaryBackendStartup>({ _tag: "Starting" }),
databaseMigrationProgress: Ref.make<DatabaseMigrationProgress | null>(null),
});

export const layer = Layer.effect(DesktopState, make);
71 changes: 67 additions & 4 deletions apps/desktop/src/backend/DesktopBackendManager.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,9 @@ interface MakeInstanceInput {
readonly onReady?: Effect.Effect<void>;
readonly onShutdown?: Effect.Effect<void>;
readonly onStateDirOwned?: Effect.Effect<void>;
readonly onMigrationProgress?: (
progress: { current: number; total: number } | null,
) => Effect.Effect<void>;
readonly onStartupFailure?: (
failure: DesktopBackendManager.BackendStartupFailure,
) => Effect.Effect<void>;
Expand Down Expand Up @@ -193,6 +196,7 @@ function makeTestInstance(input: MakeInstanceInput) {
...(input.onStateDirOwned ? { onStateDirOwned: () => input.onStateDirOwned! } : {}),
...(input.onPreflightFailed ? { onPreflightFailed: input.onPreflightFailed } : {}),
...(input.onStartupFailure ? { onStartupFailure: input.onStartupFailure } : {}),
...(input.onMigrationProgress ? { onMigrationProgress: input.onMigrationProgress } : {}),
});

return instance.pipe(Effect.provide(layerServices));
Expand Down Expand Up @@ -695,7 +699,8 @@ describe("DesktopBackendManager", () => {
"reports exit $code with the server output after $exits exits",
({ code, exits, managedPolicy }) =>
Effect.gen(function* () {
const message = "Error: Cannot find module 'zod/v4' in /Users/René";
const message = `${DATABASE_MIGRATION_PROGRESS_MESSAGE} (1 of 3)\n progress: 1 of 3\nError: Cannot find module 'zod/v4' in /Users/René`;
const progress: Array<{ current: number; total: number } | null> = [];
let exitCount = 0;
const firstExit = yield* Deferred.make<void>();
const reports = yield* Queue.unbounded<{
Expand Down Expand Up @@ -729,6 +734,10 @@ describe("DesktopBackendManager", () => {
return Deferred.succeed(firstExit, undefined).pipe(Effect.asVoid);
},
},
onMigrationProgress: (value) =>
Effect.sync(() => {
progress.push(value);
}),
onStartupFailure: (failure) =>
Queue.offer(reports, { exitCount, failure }).pipe(Effect.asVoid),
});
Expand All @@ -741,35 +750,54 @@ describe("DesktopBackendManager", () => {
assert.equal(failure.managedPolicy, managedPolicy);
assert.isTrue(failure.output.endsWith(message));
assert.isTrue(failure.output.isWellFormed());
assert.isTrue(progress.some((value) => value?.current === 1 && value.total === 3));
assert.isNull(progress.at(-1));
}).pipe(Effect.provide(TestClock.layer())),
);

it.effect("waits out a slow startup and reports one that never becomes ready", () =>
Effect.gen(function* () {
const reports = yield* Queue.unbounded<DesktopBackendManager.BackendStartupFailure>();
const startInstance = (status: Ref.Ref<number>, onReady?: Effect.Effect<void>, stdout = "") =>
const progress: Array<{ current: number; total: number } | null> = [];
const outputProcessed = yield* Queue.unbounded<void>();
const startInstance = (
status: Ref.Ref<number>,
onReady?: Effect.Effect<void>,
stdout: string | Stream.Stream<Uint8Array> = "",
) =>
makeTestInstance({
spawnerLayer: Layer.succeed(
ChildProcessSpawner.ChildProcessSpawner,
ChildProcessSpawner.make(() =>
Effect.succeed(
makeProcess({
exitCode: Effect.never,
stdout: Stream.make(new TextEncoder().encode(stdout)),
stdout:
typeof stdout === "string"
? Stream.make(new TextEncoder().encode(stdout))
: stdout,
}),
),
),
),
httpClientLayer: layerHttpClient((request) =>
Ref.get(status).pipe(Effect.map((code) => responseForRequest(request, code))),
),
backendOutputLog: {
writeOutputChunk: () => Queue.offer(outputProcessed, undefined).pipe(Effect.asVoid),
},
onMigrationProgress: (value) =>
Effect.sync(() => {
progress.push(value);
}),
onStartupFailure: (failure) => Queue.offer(reports, failure).pipe(Effect.asVoid),
...(onReady ? { onReady } : {}),
}).pipe(Effect.tap((instance) => instance.start));

const slowStatus = yield* Ref.make(503);
const ready = yield* Deferred.make<void>();
yield* startInstance(slowStatus, Deferred.succeed(ready, undefined).pipe(Effect.asVoid));
yield* Queue.take(outputProcessed);
yield* TestClock.adjust(Duration.seconds(66));
yield* Ref.set(slowStatus, 200);
yield* TestClock.adjust(Duration.millis(100));
Expand All @@ -778,22 +806,56 @@ describe("DesktopBackendManager", () => {

const migratingStatus = yield* Ref.make(503);
const migrated = yield* Deferred.make<void>();
const output = yield* Queue.unbounded<Uint8Array>();
const writeOutput = (text: string) =>
Queue.offer(output, new TextEncoder().encode(text)).pipe(
Effect.andThen(Queue.take(outputProcessed)),
);
yield* startInstance(
migratingStatus,
Deferred.succeed(migrated, undefined).pipe(Effect.asVoid),
Stream.fromQueue(output),
);
yield* writeOutput(`INFO ${DATABASE_MIGRATIONS_STARTED_MESSAGE}\n`);
yield* TestClock.adjust(Duration.minutes(3));
assert.isNull(progress.at(-1));
assert.isTrue(Option.isNone(yield* Queue.poll(reports)));
yield* writeOutput(
// Enough progress lines that the start line scrolls out of the output tail.
`INFO ${DATABASE_MIGRATIONS_STARTED_MESSAGE}\n` +
Array.from(
{ length: 80 },
(_, index) =>
`INFO ${DATABASE_MIGRATION_PROGRESS_MESSAGE} migration=${index}_Migration progress="${index + 1} of 80"\n`,
`INFO ${DATABASE_MIGRATION_PROGRESS_MESSAGE} (${index + 1} of 80)\n migration: ${index}_Migration\n progress: ${index + 1} of 80\n`,
).join(""),
);
yield* TestClock.adjust(Duration.minutes(10));
assert.deepStrictEqual(progress.at(-1), { current: 80, total: 80 });
assert.isTrue(Option.isNone(yield* Queue.poll(reports)));
const noise = "unrelated backend output\n".repeat(400);
yield* writeOutput(noise);
assert.deepStrictEqual(progress.at(-1), { current: 80, total: 80 });
yield* writeOutput(noise);
assert.deepStrictEqual(progress.at(-1), { current: 80, total: 80 });
yield* TestClock.adjust(Duration.minutes(3));
assert.isTrue(Option.isNone(yield* Queue.poll(reports)));
yield* writeOutput(`${DATABASE_MIGRATIONS_STARTED_MESSAGE}\n${noise}`);
assert.isNull(progress.at(-1));
yield* writeOutput(`${DATABASE_MIGRATION_PROGRESS_MESSAGE} (1 of 2)\n${noise}`);
assert.deepStrictEqual(progress.at(-1), { current: 1, total: 2 });
yield* writeOutput(DATABASE_MIGRATIONS_FINISHED_MESSAGE.slice(0, 12));
yield* writeOutput(`${DATABASE_MIGRATIONS_FINISHED_MESSAGE.slice(12)}\n${noise}`);
assert.isNull(progress.at(-1));
yield* writeOutput(noise);
assert.isNull(progress.at(-1));
yield* writeOutput(
`${DATABASE_MIGRATIONS_STARTED_MESSAGE}\n${DATABASE_MIGRATION_PROGRESS_MESSAGE} (1 of 1)\n`,
);
assert.deepStrictEqual(progress.at(-1), { current: 1, total: 1 });
yield* Ref.set(migratingStatus, 200);
yield* TestClock.adjust(Duration.millis(100));
yield* Deferred.await(migrated);
assert.isNull(progress.at(-1));

yield* startInstance(
yield* Ref.make(503),
Expand All @@ -804,6 +866,7 @@ describe("DesktopBackendManager", () => {
assert.isTrue(Option.isNone(yield* Queue.poll(reports)));
yield* TestClock.adjust(Duration.seconds(1));
const failure = yield* Queue.take(reports);
assert.isNull(progress.at(-1));
assert.equal(failure.reason, "The server started but did not become ready in time.");
}).pipe(Effect.provide(TestClock.layer())),
);
Expand Down
52 changes: 44 additions & 8 deletions apps/desktop/src/backend/DesktopBackendManager.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,12 @@ import {
PRIMARY_LOCAL_ENVIRONMENT_ID,
DesktopTelemetryControlMessage,
type DesktopTelemetryControlMessage as DesktopTelemetryControlMessageValue,
type DatabaseMigrationProgress,
} from "@t3tools/contracts";
import { isRunningDatabaseMigrations } from "@t3tools/shared/databaseMigrationLog";
import {
databaseMigrationProgress,
isRunningDatabaseMigrations,
} from "@t3tools/shared/databaseMigrationLog";
import { waitForHttpReady as waitForHttpReadyShared } from "@t3tools/shared/httpReadiness";

import * as DesktopObservability from "../app/DesktopObservability.ts";
Expand Down Expand Up @@ -260,6 +264,9 @@ export interface BackendInstanceSpec {
readonly onStateDirOwned?: () => Effect.Effect<void>;
/** Fires on each repeated crash or readiness timeout until the backend becomes ready. */
readonly onStartupFailure?: (failure: BackendStartupFailure) => Effect.Effect<void>;
readonly onMigrationProgress?: (
progress: DatabaseMigrationProgress | null,
) => Effect.Effect<void>;
}

interface ActiveBackendRun {
Expand Down Expand Up @@ -685,6 +692,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
const state = yield* SubscriptionRef.make(initialState);
const mutex = yield* Semaphore.make(1);
const outputTail = yield* Ref.make("");
const migrationProgress = yield* Ref.make<DatabaseMigrationProgress | null>(null);
// One streaming decoder per stream keeps UTF-8 characters split across chunks intact.
const makeOutputDecoders = () => ({ stdout: new TextDecoder(), stderr: new TextDecoder() });
let outputDecoders = makeOutputDecoders();
Expand Down Expand Up @@ -911,6 +919,8 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
);

if (isCurrentRun) {
yield* Ref.set(migrationProgress, null);
yield* spec.onMigrationProgress?.(null) ?? Effect.void;
yield* desktopTelemetryPublisher.removeControlSource(spec.id);
if (Option.isSome(pid)) {
if (exitObserved && !stopRequested) {
Expand Down Expand Up @@ -954,6 +964,8 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
pid: Option.some(pid),
}));
yield* Ref.set(outputTail, "");
yield* Ref.set(migrationProgress, null);
yield* spec.onMigrationProgress?.(null) ?? Effect.void;
outputDecoders = makeOutputDecoders();
yield* backendOutputLog.beginSession({
details: `pid=${pid} port=${config.value.bootstrap.port} cwd=${config.value.cwd}`,
Expand Down Expand Up @@ -984,6 +996,8 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
return;
}

yield* Ref.set(migrationProgress, null);
yield* spec.onMigrationProgress?.(null) ?? Effect.void;
yield* spec.onReady?.(config.value.httpBaseUrl, pid) ?? Effect.void;
if (
config.value.runningDistro !== undefined &&
Expand All @@ -997,7 +1011,10 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
}),
onReadinessFailure: Effect.fn("desktop.backendInstance.onReadinessFailure")(
function* (error) {
if (isRunningDatabaseMigrations(yield* Ref.get(outputTail))) {
if (
(yield* Ref.get(migrationProgress)) !== null ||
isRunningDatabaseMigrations(yield* Ref.get(outputTail))
) {
yield* logInstanceWarning("backend is still migrating its database; waiting", {
error: error.message,
});
Expand All @@ -1013,12 +1030,31 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
},
),
onOutput: (streamName, chunk) =>
Ref.update(outputTail, (tail) =>
// A cut through a surrogate pair would make encodeURIComponent throw when rendering.
(tail + outputDecoders[streamName].decode(chunk, { stream: true }))
.slice(-STARTUP_FAILURE_OUTPUT_CHARS)
.toWellFormed(),
).pipe(Effect.andThen(backendOutputLog.writeOutputChunk(streamName, chunk))),
Ref.modify(outputTail, (tail) => {
const output = tail + outputDecoders[streamName].decode(chunk, { stream: true });
return [
output,
// A cut through a surrogate pair would make encodeURIComponent throw when rendering.
output.slice(-STARTUP_FAILURE_OUTPUT_CHARS).toWellFormed(),
];
}).pipe(
Effect.flatMap((output) =>
Effect.gen(function* () {
const latest = yield* SubscriptionRef.get(state);
if (
!latest.ready &&
Option.isSome(latest.active) &&
latest.active.value.id === runId
) {
const progress = yield* Ref.updateAndGet(migrationProgress, (previous) =>
databaseMigrationProgress(output, previous),
);
yield* spec.onMigrationProgress?.(progress) ?? Effect.void;
}
}),
),
Effect.andThen(backendOutputLog.writeOutputChunk(streamName, chunk)),
),
}).pipe(
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
Effect.provideService(HttpClient.HttpClient, httpClient),
Expand Down
4 changes: 3 additions & 1 deletion apps/desktop/src/backend/DesktopBackendPool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import * as Context from "effect/Context";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Ref from "effect/Ref";
import * as Exit from "effect/Exit";
import * as FiberHandle from "effect/FiberHandle";
import * as Layer from "effect/Layer";
Expand Down Expand Up @@ -126,7 +127,7 @@ export const layer = Layer.effect(
const electronDialog = yield* ElectronDialog.ElectronDialog;
const electronApp = yield* ElectronApp.ElectronApp;
const appSettings = yield* DesktopAppSettings.DesktopAppSettings;
const { primaryBackendStartup } = yield* DesktopState.DesktopState;
const { primaryBackendStartup, databaseMigrationProgress } = yield* DesktopState.DesktopState;
// Parent instance scopes to the pool so shutdown runs stop finalizers before the OS kills backends.
const layerScope = yield* Scope.Scope;
const factoryContext = yield* Effect.context<BackendInstanceFactoryRequirements>();
Expand Down Expand Up @@ -241,6 +242,7 @@ export const layer = Layer.effect(
),
onStartupFailure: (failure) =>
SubscriptionRef.set(primaryBackendStartup, { _tag: "Failing", ...failure }),
onMigrationProgress: (progress) => Ref.set(databaseMigrationProgress, progress),
onShutdown: () =>
FiberHandle.clear(updateMarkerWait).pipe(
Effect.andThen(desktopWindow.handleBackendNotReady),
Expand Down
2 changes: 2 additions & 0 deletions apps/desktop/src/ipc/DesktopIpcHandlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import {
} from "./methods/updates.ts";
import {
getAppBranding,
getDatabaseMigrationProgress,
getLocalEnvironmentBootstraps,
getLocalEnvironmentBearerToken,
installRelayTelemetryEnabled,
Expand Down Expand Up @@ -100,6 +101,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
yield* ipc.handleSync(takeLegacyLocalStorage);
yield* ipc.handle(completeLegacyLocalStorage);
yield* ipc.handleSync(getAppBranding);
yield* ipc.handle(getDatabaseMigrationProgress);
yield* installRelayTelemetryEnabled();
yield* ipc.handleSync(getSystemLocale);
yield* ipc.handleSync(getPreferredSystemLanguages);
Expand Down
1 change: 1 addition & 0 deletions apps/desktop/src/ipc/channels.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ export const CLI_COMMAND_INSTALL_CHANNEL = "desktop:cli-command-install";
export const CLI_COMMAND_UNINSTALL_CHANNEL = "desktop:cli-command-uninstall";
export const CLI_COMMAND_ADD_TO_PATH_CHANNEL = "desktop:cli-command-add-to-path";
export const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
export const GET_DATABASE_MIGRATION_PROGRESS_CHANNEL = "desktop:get-database-migration-progress";
export const GET_RELAY_TELEMETRY_ENABLED_CHANNEL = "desktop:get-relay-telemetry-enabled";
export const GET_SYSTEM_LOCALE_CHANNEL = "desktop:get-system-locale";
export const GET_PREFERRED_SYSTEM_LANGUAGES_CHANNEL = "desktop:get-preferred-system-languages";
Expand Down
13 changes: 13 additions & 0 deletions apps/desktop/src/ipc/methods/window.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import {
ContextMenuItemSchema,
ContextMenuSource,
DesktopAppBrandingSchema,
DatabaseMigrationProgress,
DesktopEnvironmentBootstrapSchema,
DesktopMediaReadSchema,
DesktopThemeSchema,
Expand All @@ -25,6 +26,8 @@ import * as Path from "effect/Path";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import * as Ref from "effect/Ref";
import * as DesktopState from "../../app/DesktopState.ts";

import * as DesktopBackendConfiguration from "../../backend/DesktopBackendConfiguration.ts";
import * as DesktopBackendManager from "../../backend/DesktopBackendManager.ts";
Expand Down Expand Up @@ -74,6 +77,16 @@ function toWebSocketBaseUrl(httpBaseUrl: URL): string {
return url.href;
}

export const getDatabaseMigrationProgress = DesktopIpc.makeIpcMethod({
channel: IpcChannels.GET_DATABASE_MIGRATION_PROGRESS_CHANNEL,
payload: Schema.Void,
result: Schema.NullOr(DatabaseMigrationProgress),
handler: Effect.fn("desktop.ipc.window.getDatabaseMigrationProgress")(function* () {
const state = yield* DesktopState.DesktopState;
return yield* Ref.get(state.databaseMigrationProgress);
}),
});

export const getAppBranding = DesktopIpc.makeSyncIpcMethod({
channel: IpcChannels.GET_APP_BRANDING_CHANNEL,
result: Schema.NullOr(DesktopAppBrandingSchema),
Expand Down
2 changes: 2 additions & 0 deletions apps/desktop/src/preload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ function unwrapEnsureSshEnvironmentResult(result: unknown) {
}

contextBridge.exposeInMainWorld("desktopBridge", {
getDatabaseMigrationProgress: () =>
ipcRenderer.invoke(IpcChannels.GET_DATABASE_MIGRATION_PROGRESS_CHANNEL),
getAppBranding: () => {
const result = ipcRenderer.sendSync(IpcChannels.GET_APP_BRANDING_CHANNEL);
if (typeof result !== "object" || result === null) {
Expand Down
Loading
Loading