Files
Netcatty/electron/bridges/terminalEncoding.cjs
T
陈大猫andClaude Opus 4.8 0b8206aecb fix(terminal): encode input with the session charset (#1216) (#1222)
The terminal output path decodes remote bytes with an iconv decoder built
from the user's configured charset (GB18030, etc.), but the input path
serialized keystrokes as UTF-8 unconditionally. On a non-UTF-8 device that
made input and output asymmetric: with GB18030 selected the device's command
completion decoded correctly while manually typed Chinese went out as UTF-8
bytes and showed up garbled (and the reverse with UTF-8 selected).

Make input symmetric with output:

- Add electron/bridges/terminalEncoding.cjs as the single source of truth for
  charset normalization plus encodeTerminalInput(), which encodes a keystroke
  string with the same iconv charset (returning the string untouched for UTF-8
  and for unset/unknown encodings so the transport's native serialization and
  the Mosh/local-PTY paths are unchanged). ASCII control bytes and CSI escape
  sequences pass through byte-for-byte under GB18030.
- terminalBridge.writeToSession() now encodes outgoing data via
  encodeTerminalInput(session.encoding) before writing to the SSH stream,
  telnet socket, or serial port. Telnet IAC 0xFF escaping still runs on the
  encoded bytes.
- session.encoding (the input charset) is now kept in lock-step with the
  output decoder everywhere the decoder is configured:
    * Telnet/serial already stored session.encoding; writeToSession now reads
      it for input too.
    * SSH mirrors session.encoding wherever it sets sessionEncodings: the
      GB-variant pre-seed at session start and the runtime setEncoding handler.
      The pre-seed stays gated to GB variants to match the renderer's two-value
      encoding state, so behavior for other/arbitrary charsets is unchanged —
      the renderer still pushes the effective encoding via setEncoding on
      attach, and that handler keeps both halves in sync.
- The SSH startup command is encoded with the same charset as interactive
  input.

Mosh stays UTF-8 (mosh-client is UTF-8-only and sets LANG accordingly), and
local PTY stays UTF-8 — neither sets session.encoding, so their input is
untouched.

Adds unit tests for the encoding helper (GB18030/UTF-8 round-trips, ASCII
control preservation, symmetry with the output decoder) and integration tests
driving writeToSession over a raw TCP device to assert GB18030 bytes on the
wire and a UTF-8 regression guard.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 19:08:21 +08:00

99 lines
4.6 KiB
JavaScript

/**
* Terminal encoding helpers — the single source of truth for turning a
* user-facing charset name into an iconv-lite identifier and for keeping the
* terminal input (keystrokes → remote) and output (remote → display) paths on
* the *same* encoding.
*
* Background (issue #1216): the output path already decodes remote bytes with
* an iconv decoder built from the user's configured charset (GB18030, etc.),
* but the input path used to serialize keystrokes as UTF-8 unconditionally.
* On a non-UTF-8 device that made input and output asymmetric — typing Chinese
* showed up garbled on the device while the device's own output decoded fine
* (or vice-versa, depending on which side the user matched). Encoding input
* with the *same* charset closes that gap.
*/
const iconv = require("iconv-lite");
// Normalize user-facing charset names into an iconv-lite encoding identifier.
// iconv-lite accepts a wide range of aliases directly ("utf-8", "gbk", etc.),
// so mostly this just lowercases + collapses non-alphanumerics and maps a few
// obvious GB* variants to gb18030 which is the superset we ship the encoding
// switcher with. Anything iconv doesn't recognize falls back to utf-8.
function normalizeTerminalEncoding(charset) {
if (!charset) return "utf-8";
const raw = String(charset).trim().toLowerCase();
const normalized = raw.replace(/[^a-z0-9]/g, "");
if (["utf8", "utf-8"].includes(normalized)) return "utf-8";
if (normalized === "gb18030" || normalized === "gbk" || normalized === "gb2312") return "gb18030";
return iconv.encodingExists(raw) ? raw : "utf-8";
}
// True when the encoding is UTF-8 (the JS/Node default for string → bytes).
// Callers use this to skip the iconv round-trip on the hot input path: for
// UTF-8 the platform's native string serialization is already correct, so
// there is nothing to convert.
function isUtf8Encoding(encoding) {
if (!encoding) return true;
return /^utf-?8$/i.test(String(encoding).trim());
}
// Cache of encoding identifier -> whether it is ASCII-compatible (each ASCII
// byte encodes to exactly itself, one byte). iconv probing is cheap but this is
// the keystroke hot path, so memoize it.
const asciiCompatibleCache = new Map();
// A terminal speaks ASCII control bytes: CR, LF, ESC and the bytes of CSI
// escape sequences (Enter, arrows, Ctrl-C, …). Encodings like GB18030 / GBK /
// Big5 / Shift_JIS / EUC / latin1 are ASCII supersets, so those bytes survive
// untouched and only the non-ASCII characters change. But ASCII-incompatible
// multi-byte encodings (UTF-16LE/BE, UCS-2, UTF-32, …) would turn "\r" into
// `0d 00` and "\x1b[A" into `1b 00 5b 00 41 00`, breaking line discipline and
// escape parsing on the remote. We probe a representative ASCII control byte
// and refuse to use iconv for input on encodings that don't preserve it.
function isAsciiCompatibleEncoding(encoding) {
const cached = asciiCompatibleCache.get(encoding);
if (cached !== undefined) return cached;
let compatible = false;
try {
// \r and ESC cover the control bytes we care about; a single C0 probe is
// enough since ASCII-incompatible encodings widen every code point.
const cr = iconv.encode("\r", encoding);
const esc = iconv.encode("\x1b", encoding);
compatible = cr.length === 1 && cr[0] === 0x0d && esc.length === 1 && esc[0] === 0x1b;
} catch {
compatible = false;
}
asciiCompatibleCache.set(encoding, compatible);
return compatible;
}
/**
* Encode a terminal input string for the wire using the session's charset.
*
* Returns the original string unchanged for UTF-8 (let the transport's native
* string handling serialize it) and a Buffer encoded with iconv-lite for any
* other ASCII-compatible charset. ASCII control bytes (CR, ESC, Ctrl-C, the
* bytes of CSI escape sequences, …) stay single-byte under those encodings, so
* encoding the whole string is safe — only the non-ASCII characters change.
*
* `encoding` is expected to already be a normalized iconv identifier (what
* normalizeTerminalEncoding returns and what sessions store on
* `session.encoding`). Falls back to the UTF-8 string — i.e. today's behavior —
* for unknown encodings and for ASCII-incompatible ones (UTF-16/UCS-2/…) where
* widening the control bytes would break Enter / arrows / Ctrl-C on the remote.
*/
function encodeTerminalInput(data, encoding) {
if (typeof data !== "string") return data;
if (isUtf8Encoding(encoding)) return data;
if (!iconv.encodingExists(encoding)) return data;
if (!isAsciiCompatibleEncoding(encoding)) return data;
return iconv.encode(data, encoding);
}
module.exports = {
normalizeTerminalEncoding,
isUtf8Encoding,
encodeTerminalInput,
};