Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Change-log.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Change Log

# Unreleased

- Preserve Unicode surrogate pairs when splitting large text frames; reject a one-unit chunk size before sending a frame that requires a pair.

# 7.5.0 (2026-10-15)

- Fix [#743](https://github.com/stomp-js/stompjs/issues/743)
Expand Down
221 changes: 221 additions & 0 deletions spec/unit/split-frames-unicode.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
import { expect, test } from '@playwright/test';
import { Client, FrameImpl, StompConfig } from '../../src/index.js';
import { IStompSocket } from '../../src/types.js';

// Each text send is encoded separately, as it is by a WebSocket transport.
class RecordingSocket implements IStompSocket {
public url = 'ws://test.invalid';
public readyState = 0;
public binaryType = 'arraybuffer';
public onopen: IStompSocket['onopen'] = null;
public onclose: IStompSocket['onclose'] = null;
public onerror: IStompSocket['onerror'] = null;
public onmessage: IStompSocket['onmessage'] = null;
public sent: Parameters<IStompSocket['send']>[0][] = [];
public wire: Uint8Array[] = [];
private pending = '';

constructor() {
queueMicrotask(() => {
this.readyState = 1;
this.onopen?.();
});
}

public send(data: Parameters<IStompSocket['send']>[0]): void {
const bytes =
typeof data === 'string'
? new TextEncoder().encode(data)
: ArrayBuffer.isView(data)
? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
: new Uint8Array(data as ArrayBuffer);
this.sent.push(data);
this.wire.push(bytes);
this.pending += new TextDecoder().decode(bytes);
if (
this.pending.endsWith('\0') &&
(this.pending.startsWith('CONNECT\n') ||
this.pending.startsWith('STOMP\n'))
) {
this.pending = '';
queueMicrotask(() =>
this.onmessage?.({
data: 'CONNECTED\nversion:1.2\nheart-beat:0,0\n\n\0',
}),
);
}
}

public close(): void {
this.readyState = 3;
this.onclose?.({ code: 1000, reason: '', wasClean: true });
}
}

const destination = '/queue/unicode';

function expectedFrame(body: string): string {
return FrameImpl.marshall({
command: 'SEND',
headers: { destination },
body,
escapeHeaderValues: true,
}) as string;
}

async function connectedClient(options: StompConfig) {
let socket: RecordingSocket;
const client = new Client({
reconnectDelay: 0,
heartbeatIncoming: 0,
heartbeatOutgoing: 0,
splitLargeFrames: true,
...options,
webSocketFactory: () => (socket = new RecordingSocket()),
});
const connected = new Promise<void>(resolve => {
client.onConnect = () => resolve();
});
client.activate();
await connected;
socket!.sent = [];
socket!.wire = [];
return { client, socket: socket! };
}

function wireText(socket: RecordingSocket): string {
const length = socket.wire.reduce((total, chunk) => total + chunk.length, 0);
const bytes = new Uint8Array(length);
let offset = 0;
for (const chunk of socket.wire) {
bytes.set(chunk, offset);
offset += chunk.length;
}
return new TextDecoder().decode(bytes);
}

test.describe('split text frames with Unicode', () => {
for (const size of [2, 3, 8192]) {
for (const character of ['😀', '𝄞']) {
test(`preserves ${character} across a ${size}-unit boundary`, async () => {
const { client, socket } = await connectedClient({
maxWebSocketChunkSize: size,
});
try {
let body = '';
for (let padding = 0; padding < size; padding++) {
const candidate = 'a'.repeat(padding) + character + 'tail';
if (
expectedFrame(candidate).indexOf(character) % size ===
size - 1
) {
body = candidate;
break;
}
}
expect(body).not.toBe('');
client.publish({ destination, body });
expect(wireText(socket)).toBe(expectedFrame(body));
expect(socket.sent.length).toBeGreaterThan(1);
for (const chunk of socket.sent) {
expect(typeof chunk).toBe('string');
expect((chunk as string).length).toBeGreaterThan(0);
expect((chunk as string).length).toBeLessThanOrEqual(size);
}
} finally {
await client.deactivate({ force: true });
}
});
}
}

for (const body of ['😀tail', 'middle😀tail', 'tail😀']) {
test(`rejects one-unit chunks before sending ${body}`, async () => {
const { client, socket } = await connectedClient({
maxWebSocketChunkSize: 1,
});
try {
expect(() => client.publish({ destination, body })).toThrow(RangeError);
expect(socket.sent).toHaveLength(0);
expect(socket.wire).toHaveLength(0);
client.publish({ destination, body: 'safe ASCII' });
expect(wireText(socket)).toBe(expectedFrame('safe ASCII'));
} finally {
await client.deactivate({ force: true });
}
});
}

test('checks headers before sending any part of a one-unit frame', async () => {
const { client, socket } = await connectedClient({
maxWebSocketChunkSize: 1,
});
try {
expect(() =>
client.publish({
destination,
headers: { label: '😀' },
body: 'ASCII',
}),
).toThrow(RangeError);
expect(socket.sent).toHaveLength(0);
} finally {
await client.deactivate({ force: true });
}
});

for (const body of ['ASCII', 'é漢字', '\ud800x\udc00']) {
test(`preserves existing text encoding for ${JSON.stringify(body)}`, async () => {
const { client, socket } = await connectedClient({
maxWebSocketChunkSize: 1,
});
try {
client.publish({ destination, body });
const encoded = new TextEncoder().encode(expectedFrame(body));
expect(wireText(socket)).toBe(new TextDecoder().decode(encoded));
expect(socket.sent.every(chunk => (chunk as string).length === 1)).toBe(
true,
);
} finally {
await client.deactivate({ force: true });
}
});
}

for (const options of [
{ splitLargeFrames: false },
{ forceBinaryWSFrames: true },
]) {
test(`does not change the unsplit path ${JSON.stringify(options)}`, async () => {
const { client, socket } = await connectedClient({
maxWebSocketChunkSize: 1,
...options,
});
try {
client.publish({ destination, body: '😀' });
expect(wireText(socket)).toBe(expectedFrame('😀'));
expect(socket.sent).toHaveLength(1);
expect(typeof socket.sent[0] === 'string').toBe(
!options.forceBinaryWSFrames,
);
} finally {
await client.deactivate({ force: true });
}
});
}

test('does not split a binary body', async () => {
const { client, socket } = await connectedClient({
maxWebSocketChunkSize: 1,
});
try {
const bytes = new TextEncoder().encode('😀');
client.publish({ destination, binaryBody: bytes });
expect(socket.sent).toHaveLength(1);
expect(typeof socket.sent[0]).not.toBe('string');
expect(wireText(socket)).toBe(expectedFrame('😀'));
} finally {
await client.deactivate({ force: true });
}
});
});
7 changes: 4 additions & 3 deletions src/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -229,15 +229,16 @@ export class Client {
* Example:
* ```javascript
* client.splitLargeFrames = true;
* client.maxWebSocketChunkSize = 4096; // Allow chunks of 4 KB
* client.maxWebSocketChunkSize = 4096; // Allow chunks of 4096 UTF-16 code units
* ```
*/
public splitLargeFrames: boolean = false;

/**
* Maximum size (in bytes) for individual WebSocket chunks if [splitLargeFrames]{@link Client#splitLargeFrames} is enabled.
* Maximum size (in UTF-16 code units) for individual text WebSocket chunks if [splitLargeFrames]{@link Client#splitLargeFrames} is enabled.
*
* Default is 8 KB (`8 * 1024` bytes). This value has no effect if [splitLargeFrames]{@link Client#splitLargeFrames} is `false`.
* Default is `8 * 1024` UTF-16 code units. This value has no effect if [splitLargeFrames]{@link Client#splitLargeFrames} is `false`.
* Text chunks preserve surrogate pairs. A value of `1` throws a `RangeError` before sending a text frame containing such a pair.
*/
public maxWebSocketChunkSize: number = 8 * 1024;

Expand Down
22 changes: 20 additions & 2 deletions src/stomp-handler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -418,9 +418,27 @@ export class StompHandler {
this._webSocket.send(rawChunk);
} else {
let out = rawChunk as string;
if (
this.maxWebSocketChunkSize < 2 &&
/[\uD800-\uDBFF][\uDC00-\uDFFF]/.test(out)
) {
throw new RangeError(
'maxWebSocketChunkSize must be at least 2 to split surrogate pairs',
);
}
while (out.length > 0) {
const chunk = out.substring(0, this.maxWebSocketChunkSize);
out = out.substring(this.maxWebSocketChunkSize);
let chunk = out.substring(0, this.maxWebSocketChunkSize);
const last = chunk.charCodeAt(chunk.length - 1);
const next = out.charCodeAt(chunk.length);
if (
last >= 0xd800 &&
last <= 0xdbff &&
next >= 0xdc00 &&
next <= 0xdfff
) {
chunk = chunk.substring(0, chunk.length - 1);
}
out = out.substring(chunk.length);
this._webSocket.send(chunk);
this.debug(`chunk sent = ${chunk.length}, remaining = ${out.length}`);
}
Expand Down