@hydranium/client-theia 1.0.0-next.18 → 1.0.0-next.180

package/src/browser/hydranium-file-service.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type URI from '@theia/core/lib/common/uri';
+import { injectable } from '@theia/core/shared/inversify';
+import { FileService, type UpdateTextFileOptions } from '@theia/filesystem/lib/browser/file-service';
+import { ETAG_DISABLED } from '@theia/filesystem/lib/common/files';
+
+/**
+ * Theia's `FileService`, refusing an incremental save once the file has
+ * changed since the editor read it.
+ *
+ * Theia's own check, which `write` and `update` share, passes a file whose
+ * mtime moved on when its size still matches the etag the editor read. That
+ * is safe for `write`, which replaces the file with the whole text, but
+ * `update` applies the editor's pending edits to the file as it is, so after a
+ * same-size change, the server saving those very edits included, it applies
+ * them a second time. Here `update` hands that check the etag with a `!`
+ * appended, which no file's etag can match: Theia writes an etag as the mtime
+ * in base 29 followed by the size in base 31, digits and lower-case letters
+ * only. An advanced mtime is then enough for Theia to refuse with its
+ * `FILE_MODIFIED_SINCE`. The editor's save then falls back to `write` with the
+ * whole text, which Theia checks as before: it writes when the size is
+ * unchanged, and asks the user otherwise. A same-size change by another
+ * process is therefore overwritten by that write rather than merged with the
+ * editor's edits. `write` is left as it is.
+ *
+ * It is the safety net behind `EditorDiskSync`, which acts only when the
+ * file holds the editor's buffer: a file holding some of the edits, as when a
+ * save participant ordered ahead of Theia's first one edits before its first
+ * await, is left to this check.
+ *
+ * A write within the file system's mtime resolution of the read goes unseen,
+ * as it does for Theia's own check. A file whose mtime moves while its text
+ * stays the same costs a whole-text write rather than the edits.
+ *
+ * The adopter binds it with `rebind(FileService).to(HydraniumFileService).inSingletonScope()`.
+ */
+@injectable()
+export class HydraniumFileService extends FileService {
+   override update(
+      resource: URI,
+      changes: Parameters<FileService['update']>[1],
+      options: UpdateTextFileOptions
+   ): ReturnType<FileService['update']> {
+      const strict =
+         typeof options.etag === 'string' && options.etag !== ETAG_DISABLED ? { ...options, etag: `${options.etag}!` } : options;
+      return super.update(resource, changes, strict);
+   }
+}

package/src/browser/index.ts

@@ -12,3 +12,8 @@ export * from './channel-logger';
 export * from './log-level-preference';
 export * from './browser-capture';
 export * from './memory-diagnostics-contribution';
+export * from './session-aware-connection-source';
+export * from './connection-diagnostics-contribution';
+export * from './connection-reporter';
+export * from './editor-disk-sync';
+export * from './hydranium-file-service';

package/src/browser/log-level-preference.ts

@@ -108,7 +108,18 @@ export class LogLevelPreferenceContribution implements FrontendApplicationContri
    protected applyLevel(): void {
       const level = parseLogLevel(this.preferences.get<string>(this.preferenceName));
       if (level) {
+         const previous = Logger.getLevel();
          Logger.setLevel(level);
+         if (previous !== level) {
+            // Through Theia's `ILogger`, which has a threshold of its own and so
+            // is not silenced by the value just applied — the framework logger
+            // this preference governs would drop the line on a switch to `error`.
+            //
+            // Frontend and server announce separately: this preference reaches
+            // the server only if a client delivers it as configuration, so one
+            // line without the other says it did not.
+            this.logger.info(`Log level ${previous} → ${level} (preference '${this.preferenceName}')`);
+         }
       }
    }
 }

package/src/browser/memory-diagnostics-contribution.ts

@@ -14,7 +14,7 @@ import {
    type StartProfilingArgs
 } from '@hydranium/protocol';
 import { captureBrowserRuntime, formatBrowserRuntime } from './browser-capture';
-import { CommandContribution, MessageService, type Command, type CommandRegistry } from '@theia/core';
+import { CommandContribution, MessageService, nls, type Command, type CommandRegistry } from '@theia/core';
 import { inject, injectable, optional, type interfaces } from '@theia/core/shared/inversify';
 import { OutputChannelManager, type OutputChannel } from '@theia/output/lib/browser/output-channel';
 
@@ -54,6 +54,17 @@ export const MemoryDiagnosticsService = Symbol('MemoryDiagnosticsService');
 export type HostMemoryDiagnosticsService = HostDiagnosticsProtocol;
 export const HostMemoryDiagnosticsService = Symbol('HostMemoryDiagnosticsService');
 
+/**
+ * What a `report` call captured, as a code rather than a prose fragment. The
+ * sentences it appears in are authored once per code, because a fragment
+ * substituted into a sentence is itself translatable text and a translator
+ * given the sentence alone cannot inflect around a hole.
+ */
+export type DiagnosticsSubject = 'server-state' | 'pod-memory' | 'latency' | 'backend-state' | 'profile';
+
+/** Which process a heap snapshot is taken of; a code, for the reason {@link DiagnosticsSubject} is one. */
+export type HeapSnapshotTarget = 'server' | 'backend';
+
 /**
  * Memory-diagnostics commands, one per layer reachable from the frontend. Full
  * multi-line snapshots are appended to the configured output channel; a one-line
@@ -88,76 +99,162 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
     * localized apart, leaving a button or an instruction that names a command
     * the user cannot find.
     */
-   protected readonly stopProfilingLabel: string = 'Stop Profiling (Server)';
+   protected readonly stopProfilingLabel: string = nls.localize(
+      'hydranium/client-theia/command-stop-profiling-server',
+      'Stop Profiling (Server)'
+   );
 
    registerCommands(registry: CommandRegistry): void {
       const { category } = this.options;
-      registry.registerCommand(this.command('dumpServerState', 'Dump Server State', category), {
-         execute: () => this.report('server state', () => this.diagnostics.dumpServerState({ label: new Date().toISOString() }), ['heap'])
-      });
-      registry.registerCommand(this.command('dumpPodMemory', 'Dump Pod Memory', category), {
-         execute: () => this.report('pod memory', () => this.diagnostics.dumpPodMemory(), ['current', 'rss sum'])
-      });
-      registry.registerCommand(this.command('dumpFrontendState', 'Dump Frontend State', category), {
-         execute: () => this.dumpFrontendState()
-      });
-      registry.registerCommand(this.command('writeHeapSnapshot', 'Write Heap Snapshot (Server)', category), {
-         execute: () => this.writeSnapshot('server', label => this.diagnostics.writeHeapSnapshot({ label }))
-      });
+      registry.registerCommand(
+         this.command({
+            id: 'dumpServerState',
+            label: nls.localize('hydranium/client-theia/command-dump-server-state', 'Dump Server State'),
+            category
+         }),
+         {
+            execute: () =>
+               this.report('server-state', () => this.diagnostics.dumpServerState({ label: new Date().toISOString() }), ['heap'])
+         }
+      );
+      registry.registerCommand(
+         this.command({
+            id: 'dumpPodMemory',
+            label: nls.localize('hydranium/client-theia/command-dump-pod-memory', 'Dump Pod Memory'),
+            category
+         }),
+         {
+            execute: () => this.report('pod-memory', () => this.diagnostics.dumpPodMemory(), ['current', 'rss sum'])
+         }
+      );
+      registry.registerCommand(
+         this.command({
+            id: 'dumpFrontendState',
+            label: nls.localize('hydranium/client-theia/command-dump-frontend-state', 'Dump Frontend State'),
+            category
+         }),
+         {
+            execute: () => this.dumpFrontendState()
+         }
+      );
+      registry.registerCommand(
+         this.command({
+            id: 'writeHeapSnapshot',
+            label: nls.localize('hydranium/client-theia/command-write-heap-snapshot-server', 'Write Heap Snapshot (Server)'),
+            category
+         }),
+         {
+            execute: () => this.writeSnapshot('server', label => this.diagnostics.writeHeapSnapshot({ label }))
+         }
+      );
       // Sampled profiling of the server process — sampling does NOT pause it (unlike
       // the heap snapshot). Start/Stop are the manual pair; Record wraps a fixed window.
-      registry.registerCommand(this.command('startProfiling', 'Start Profiling (Server)', category), {
-         execute: () => this.startProfiling()
-      });
-      registry.registerCommand(this.command('stopProfiling', this.stopProfilingLabel, category), {
+      registry.registerCommand(
+         this.command({
+            id: 'startProfiling',
+            label: nls.localize('hydranium/client-theia/command-start-profiling-server', 'Start Profiling (Server)'),
+            category
+         }),
+         {
+            execute: () => this.startProfiling()
+         }
+      );
+      registry.registerCommand(this.command({ id: 'stopProfiling', label: this.stopProfilingLabel, category }), {
          execute: () => this.stopProfiling()
       });
       registry.registerCommand(
-         this.command('recordProfile', `Record Performance Profile (Server, ${Math.round(this.recordDurationMs / 1000)}s)`, category),
+         this.command({
+            id: 'recordProfile',
+            // The window length rides the substitution path rather than a
+            // template literal: an extractor reads the source text, so an
+            // interpolated default is never in the catalogue at all.
+            label: nls.localize(
+               'hydranium/client-theia/command-record-profile',
+               'Record Performance Profile (Server, {0}s)',
+               this.recordDurationSeconds()
+            ),
+            category
+         }),
          {
             execute: () => this.recordProfile()
          }
       );
-      registry.registerCommand(this.command('dumpLatency', 'Dump RPC/LSP Latency (Server)', category), {
-         execute: () => this.report('RPC/LSP latency', async () => formatLatencyReport(await this.diagnostics.getLatency()), ['window'])
-      });
+      registry.registerCommand(
+         this.command({
+            id: 'dumpLatency',
+            label: nls.localize('hydranium/client-theia/command-dump-latency', 'Dump RPC/LSP Latency (Server)'),
+            category
+         }),
+         {
+            execute: () => this.report('latency', async () => formatLatencyReport(await this.diagnostics.getLatency()), ['window'])
+         }
+      );
       // Host (Theia backend) process commands — registered only when the
       // optional host-diagnostics service is bound (see HostMemoryDiagnosticsService).
       const hostDiagnostics = this.hostDiagnostics;
       if (hostDiagnostics) {
-         registry.registerCommand(this.command('dumpBackendState', 'Dump Backend State', category), {
-            execute: () => this.report('backend state', () => hostDiagnostics.dumpHostState({ label: new Date().toISOString() }), ['heap'])
-         });
-         registry.registerCommand(this.command('writeBackendHeapSnapshot', 'Write Heap Snapshot (Backend)', category), {
-            execute: () => this.writeSnapshot('backend', label => hostDiagnostics.writeHostHeapSnapshot({ label }))
-         });
+         registry.registerCommand(
+            this.command({
+               id: 'dumpBackendState',
+               label: nls.localize('hydranium/client-theia/command-dump-backend-state', 'Dump Backend State'),
+               category
+            }),
+            {
+               execute: () =>
+                  this.report('backend-state', () => hostDiagnostics.dumpHostState({ label: new Date().toISOString() }), ['heap'])
+            }
+         );
+         registry.registerCommand(
+            this.command({
+               id: 'writeBackendHeapSnapshot',
+               label: nls.localize('hydranium/client-theia/command-write-heap-snapshot-backend', 'Write Heap Snapshot (Backend)'),
+               category
+            }),
+            {
+               execute: () => this.writeSnapshot('backend', label => hostDiagnostics.writeHostHeapSnapshot({ label }))
+            }
+         );
       }
    }
 
-   protected command(id: string, label: string, category: string): Command {
-      return { id: `${this.options.commandIdPrefix}.${id}`, label, category };
+   /**
+    * Takes an object rather than positional arguments so that `label` — the one
+    * user-facing member — is addressable by name. A lint rule guarding the
+    * localization of labels has only syntax to work with, and a selector for an
+    * argument position would equally catch `id`, which must stay a bare literal.
+    */
+   protected command(spec: { id: string; label: string; category: string }): Command {
+      return { id: `${this.options.commandIdPrefix}.${spec.id}`, label: spec.label, category: spec.category };
+   }
+
+   /** The record window as whole seconds, for the label and the toast that must agree on it. */
+   protected recordDurationSeconds(): number {
+      return Math.round(this.recordDurationMs / 1000);
    }
 
    /** Run a snapshot call, append the full result to the channel, toast the first matching summary line. */
-   protected async report(what: string, produce: () => Promise<string>, summaryKeys: string[]): Promise<void> {
+   protected async report(subject: DiagnosticsSubject, produce: () => Promise<string>, summaryKeys: string[]): Promise<void> {
       try {
          const snapshot = await produce();
          this.channel().appendLine(snapshot);
          this.channel().appendLine('');
-         this.messageService.info(this.summarize(snapshot, what, summaryKeys), { timeout: 5000 });
+         this.messageService.info(this.summarize(snapshot, subject, summaryKeys), { timeout: 5000 });
       } catch (error) {
-         this.messageService.error(`Failed to dump ${what}: ${this.errorMessage(error)}`);
+         this.messageService.error(this.dumpFailedMessage(subject, this.errorMessage(error)));
       }
    }
 
-   protected async writeSnapshot(target: string, produce: (label: string) => Promise<string>): Promise<void> {
+   protected async writeSnapshot(target: HeapSnapshotTarget, produce: (label: string) => Promise<string>): Promise<void> {
       try {
-         this.messageService.info(`Writing ${target} heap snapshot — this briefly pauses that process...`, { timeout: 3000 });
+         this.messageService.info(this.writingSnapshotMessage(target), { timeout: 3000 });
          const filePath = await produce(new Date().toISOString());
-         this.channel().appendLine(`Heap snapshot (${target}) written to ${filePath}`);
-         this.messageService.info(`Heap snapshot (${target}) written to ${filePath}`, { timeout: 8000 });
+         // One sentence, shown in both places: two literals of equal value can be
+         // localized apart, leaving the channel and the toast naming different files.
+         const written = this.wroteSnapshotMessage(target, filePath);
+         this.channel().appendLine(written);
+         this.messageService.info(written, { timeout: 8000 });
       } catch (error) {
-         this.messageService.error(`Failed to write ${target} heap snapshot: ${this.errorMessage(error)}`);
+         this.messageService.error(this.writeSnapshotFailedMessage(target, this.errorMessage(error)));
       }
    }
 
@@ -166,7 +263,7 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
       try {
          await this.diagnostics.startProfiling(this.profileDimensions);
       } catch (error) {
-         this.messageService.error(`Failed to start profiling: ${this.errorMessage(error)}`);
+         this.messageService.error(this.startProfilingFailedMessage(this.errorMessage(error)));
          return;
       }
       // No timeout: the capture runs as long as the user wants it to, and an
@@ -174,7 +271,7 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
       // toast is what keeps the action live, so this resolves only once the
       // user acts on it or dismisses it.
       const chosen = await this.messageService.info(
-         'Server profiling started — sampling does not stop the process.',
+         nls.localize('hydranium/client-theia/profiling-started', 'Server profiling started — sampling does not stop the process.'),
          { timeout: 0 },
          this.stopProfilingLabel
       );
@@ -188,15 +285,27 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
       return this.report('profile', () => this.diagnostics.stopProfiling({ label: new Date().toISOString() }), ['duration']);
    }
 
+   /** One authored sentence for both start paths; identical literals in two places drift apart under translation. */
+   protected startProfilingFailedMessage(detail: string): string {
+      return nls.localize('hydranium/client-theia/error-start-profiling', 'Failed to start profiling: {0}', detail);
+   }
+
    /** Capture a fixed-length window: start, wait, stop, and report the result. */
    protected async recordProfile(): Promise<void> {
       try {
          await this.diagnostics.startProfiling(this.profileDimensions);
       } catch (error) {
-         this.messageService.error(`Failed to start profiling: ${this.errorMessage(error)}`);
+         this.messageService.error(this.startProfilingFailedMessage(this.errorMessage(error)));
          return;
       }
-      this.messageService.info(`Recording a ${Math.round(this.recordDurationMs / 1000)}s server performance profile...`, { timeout: 4000 });
+      this.messageService.info(
+         nls.localize(
+            'hydranium/client-theia/recording-profile',
+            'Recording a {0}s server performance profile...',
+            this.recordDurationSeconds()
+         ),
+         { timeout: 4000 }
+      );
       await this.delay(this.recordDurationMs);
       await this.stopProfiling();
    }
@@ -219,15 +328,129 @@ export class MemoryDiagnosticsContribution implements CommandContribution {
    }
 
    /** Pull the first line starting with one of `keys` for a one-line toast; full text is in the channel. */
-   protected summarize(snapshot: string, what: string, keys: string[]): string {
+   protected summarize(snapshot: string, subject: DiagnosticsSubject, keys: string[]): string {
       const lines = snapshot.split('\n');
       for (const key of keys) {
          const line = lines.find(entry => entry.trim().startsWith(key));
          if (line) {
-            return `Captured ${what} —${line.replace(new RegExp(`^\\s*${key}\\s*`), ` ${key} `)}`;
+            return this.capturedDetailMessage(subject, line.replace(new RegExp(`^\\s*${key}\\s*`), ` ${key} `));
          }
       }
-      return `Captured ${what} (see the ${this.options.channelName} output channel)`;
+      return this.capturedChannelMessage(subject);
+   }
+
+   /**
+    * The captured-with-detail toast. The detail is a machine-formatted figure,
+    * so it is safe as a substitution parameter; the subject is not, hence one
+    * authored sentence per subject.
+    */
+   protected capturedDetailMessage(subject: DiagnosticsSubject, detail: string): string {
+      switch (subject) {
+         case 'server-state':
+            return nls.localize('hydranium/client-theia/captured-server-state-detail', 'Captured server state —{0}', detail);
+         case 'pod-memory':
+            return nls.localize('hydranium/client-theia/captured-pod-memory-detail', 'Captured pod memory —{0}', detail);
+         case 'latency':
+            return nls.localize('hydranium/client-theia/captured-latency-detail', 'Captured RPC/LSP latency —{0}', detail);
+         case 'backend-state':
+            return nls.localize('hydranium/client-theia/captured-backend-state-detail', 'Captured backend state —{0}', detail);
+         case 'profile':
+            return nls.localize('hydranium/client-theia/captured-profile-detail', 'Captured profile —{0}', detail);
+      }
+   }
+
+   /** The captured-without-detail toast; the channel name is adopter branding, not translatable text. */
+   protected capturedChannelMessage(subject: DiagnosticsSubject): string {
+      const channelName = this.options.channelName;
+      switch (subject) {
+         case 'server-state':
+            return nls.localize(
+               'hydranium/client-theia/captured-server-state-channel',
+               'Captured server state (see the {0} output channel)',
+               channelName
+            );
+         case 'pod-memory':
+            return nls.localize(
+               'hydranium/client-theia/captured-pod-memory-channel',
+               'Captured pod memory (see the {0} output channel)',
+               channelName
+            );
+         case 'latency':
+            return nls.localize(
+               'hydranium/client-theia/captured-latency-channel',
+               'Captured RPC/LSP latency (see the {0} output channel)',
+               channelName
+            );
+         case 'backend-state':
+            return nls.localize(
+               'hydranium/client-theia/captured-backend-state-channel',
+               'Captured backend state (see the {0} output channel)',
+               channelName
+            );
+         case 'profile':
+            return nls.localize(
+               'hydranium/client-theia/captured-profile-channel',
+               'Captured profile (see the {0} output channel)',
+               channelName
+            );
+      }
+   }
+
+   /** The failed-to-dump toast; the detail is a technical error string, safe as a parameter. */
+   protected dumpFailedMessage(subject: DiagnosticsSubject, detail: string): string {
+      switch (subject) {
+         case 'server-state':
+            return nls.localize('hydranium/client-theia/error-dump-server-state', 'Failed to dump server state: {0}', detail);
+         case 'pod-memory':
+            return nls.localize('hydranium/client-theia/error-dump-pod-memory', 'Failed to dump pod memory: {0}', detail);
+         case 'latency':
+            return nls.localize('hydranium/client-theia/error-dump-latency', 'Failed to dump RPC/LSP latency: {0}', detail);
+         case 'backend-state':
+            return nls.localize('hydranium/client-theia/error-dump-backend-state', 'Failed to dump backend state: {0}', detail);
+         case 'profile':
+            return nls.localize('hydranium/client-theia/error-dump-profile', 'Failed to dump profile: {0}', detail);
+      }
+   }
+
+   protected writingSnapshotMessage(target: HeapSnapshotTarget): string {
+      switch (target) {
+         case 'server':
+            return nls.localize(
+               'hydranium/client-theia/writing-heap-snapshot-server',
+               'Writing server heap snapshot — this briefly pauses that process...'
+            );
+         case 'backend':
+            return nls.localize(
+               'hydranium/client-theia/writing-heap-snapshot-backend',
+               'Writing backend heap snapshot — this briefly pauses that process...'
+            );
+      }
+   }
+
+   protected wroteSnapshotMessage(target: HeapSnapshotTarget, filePath: string): string {
+      switch (target) {
+         case 'server':
+            return nls.localize('hydranium/client-theia/wrote-heap-snapshot-server', 'Heap snapshot (server) written to {0}', filePath);
+         case 'backend':
+            return nls.localize('hydranium/client-theia/wrote-heap-snapshot-backend', 'Heap snapshot (backend) written to {0}', filePath);
+      }
+   }
+
+   protected writeSnapshotFailedMessage(target: HeapSnapshotTarget, detail: string): string {
+      switch (target) {
+         case 'server':
+            return nls.localize(
+               'hydranium/client-theia/error-write-heap-snapshot-server',
+               'Failed to write server heap snapshot: {0}',
+               detail
+            );
+         case 'backend':
+            return nls.localize(
+               'hydranium/client-theia/error-write-heap-snapshot-backend',
+               'Failed to write backend heap snapshot: {0}',
+               detail
+            );
+      }
    }
 
    protected errorMessage(error: unknown): string {