Skip to content

Expose ClientPort communication warning callback for protocol/schema mismatch reporting #558

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
azisislm merged 3 commits into from
Mar 9, 2026
Merged

Expose ClientPort communication warning callback for protocol/schema mismatch reporting #558

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc8c479
expose ClientPort communication warning callback for protocol/schema …
azisislm Mar 9, 2026
9517fd8
do not warn log if callback set
azisislm Mar 9, 2026
ae5182b
Add optional protocol-level communication warning kinds with unknown …
azisislm Mar 9, 2026
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
101 changes: 77 additions & 24 deletions packages/lms-communication-client/src/ClientPort.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import {
} from "@lmstudio/lms-common";
import {
Channel,
normalizeCommunicationWarningKind,
deserialize,
serialize,
type BackendInterface,
Expand All @@ -27,6 +28,7 @@ import {
type ServerToClientMessage,
type SignalEndpoint,
type SignalEndpointsSpecBase,
type CommunicationWarningKind,
type WritableSignalEndpoint,
type WritableSignalEndpointsSpecBase,
} from "@lmstudio/lms-communication";
Expand Down Expand Up @@ -76,6 +78,12 @@ function defaultErrorDeserializer(
return fromSerializedError(serialized, directCause, stack);
}

export interface ClientPortCommunicationWarning {
direction: "produced" | "received";
kind: CommunicationWarningKind;
warning: string;
}

export class ClientPort<
TRpcEndpoints extends RpcEndpointsSpecBase,
TChannelEndpoints extends ChannelEndpointsSpecBase,
Expand Down Expand Up @@ -104,6 +112,9 @@ export class ClientPort<
stack?: string,
) => Error;
private verboseErrorMessage: boolean;
private readonly onCommunicationWarning?: (
communicationWarning: ClientPortCommunicationWarning,
) => void;

public constructor(
public readonly backendInterface: BackendInterface<
Expand All @@ -118,6 +129,7 @@ export class ClientPort<
parentLogger,
errorDeserializer,
verboseErrorMessage,
onCommunicationWarning,
}: {
parentLogger?: LoggerInterface;
errorDeserializer?: (
Expand All @@ -126,33 +138,43 @@ export class ClientPort<
stack?: string,
) => Error;
verboseErrorMessage?: boolean;
onCommunicationWarning?: (communicationWarning: ClientPortCommunicationWarning) => void;
} = {},
) {
this.logger = new SimpleLogger("ClientPort", parentLogger);
this.errorDeserializer = errorDeserializer ?? defaultErrorDeserializer;
this.verboseErrorMessage = verboseErrorMessage ?? true;
this.onCommunicationWarning = onCommunicationWarning;
this.transport = factory(this.receivedMessage, this.onConnected, this.errored, this.logger);
}

private communicationWarning(warning: string) {
private communicationWarning(warning: string, kind: CommunicationWarningKind = "unknown") {
if (this.producedCommunicationWarningsCount >= 5) {
return;
}
this.logger.warnText`
Produced communication warning: ${warning}

This is usually caused by communication protocol incompatibility. Please make sure you are
using the up-to-date versions of the SDK and LM Studio.
`;
if (this.onCommunicationWarning === undefined) {
this.logger.warnText`
Produced communication warning: ${warning}

This is usually caused by communication protocol incompatibility. Please make sure you are
using the up-to-date versions of the SDK and LM Studio.
`;
}
this.safeSend(
{
type: "communicationWarning",
warning,
kind,
},
"communicationWarning",
);
this.reportCommunicationWarning({
Copy link
Collaborator

@ryan-the-crayon ryan-the-crayon Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's do this. In the case that a onCommunicationWarning callback is set, no need to log the warning above.

direction: "produced",
kind,
warning,
});
this.producedCommunicationWarningsCount++;
if (this.producedCommunicationWarningsCount >= 5) {
if (this.onCommunicationWarning === undefined && this.producedCommunicationWarningsCount >= 5) {
this.logger.errorText`
5 communication warnings have been produced. Further warnings will not be printed.
`;
Expand Down Expand Up @@ -190,6 +212,7 @@ export class ClientPort<
if (openChannel === undefined) {
this.communicationWarning(
`Received channelSend for unknown channel, channelId = ${message.channelId}`,
"channelUnknown",
);
return;
}
Expand All @@ -201,7 +224,7 @@ export class ClientPort<
${deserializedMessage}. Zod error:

${Validator.prettyPrintZod("message", parsed.error)}
`);
`, "channelMessageTypeError");
return;
}
openChannel.receivedMessage(parsed.data);
Expand All @@ -212,6 +235,7 @@ export class ClientPort<
if (openChannel === undefined) {
this.communicationWarning(
`Received channelAck for unknown channel, channelId = ${message.channelId}`,
"channelUnknown",
);
return;
}
Expand All @@ -223,6 +247,7 @@ export class ClientPort<
if (openChannel === undefined) {
this.communicationWarning(
`Received channelClose for unknown channel, channelId = ${message.channelId}`,
"channelUnknown",
);
return;
}
Expand All @@ -236,6 +261,7 @@ export class ClientPort<
if (openChannel === undefined) {
this.communicationWarning(
`Received channelError for unknown channel, channelId = ${message.channelId}`,
"channelUnknown",
);
return;
}
Expand All @@ -252,7 +278,10 @@ export class ClientPort<
private receivedRpcResult(message: ServerToClientMessage & { type: "rpcResult" }) {
const ongoingRpc = this.ongoingRpcs.get(message.callId);
if (ongoingRpc === undefined) {
this.communicationWarning(`Received rpcResult for unknown rpc, callId = ${message.callId}`);
this.communicationWarning(
`Received rpcResult for unknown rpc, callId = ${message.callId}`,
"rpcUnknown",
);
return;
}
const deserializedResult = deserialize(ongoingRpc.endpoint.serialization, message.result);
Expand All @@ -263,7 +292,7 @@ export class ClientPort<
${deserializedResult}. Zod error:

${Validator.prettyPrintZod("result", parsed.error)}
`);
`, "rpcResultTypeError");
return;
}
ongoingRpc.resolve(parsed.data);
Expand All @@ -274,7 +303,10 @@ export class ClientPort<
private receivedRpcError(message: ServerToClientMessage & { type: "rpcError" }) {
const ongoingRpc = this.ongoingRpcs.get(message.callId);
if (ongoingRpc === undefined) {
this.communicationWarning(`Received rpcError for unknown rpc, callId = ${message.callId}`);
this.communicationWarning(
`Received rpcError for unknown rpc, callId = ${message.callId}`,
"rpcUnknown",
);
return;
}
const error = this.errorDeserializer(
Expand Down Expand Up @@ -313,7 +345,7 @@ export class ClientPort<
patches = ${JSON.stringify(patches, null, 2)}.

Error: ${String(error)}
`);
`, "signalUpdatePatchApplyError");
return;
}
const parseResult = openSignalSubscription.endpoint.signalData.safeParse(afterValue);
Expand All @@ -330,7 +362,7 @@ export class ClientPort<
Zod error:

${Validator.prettyPrintZod("value", parseResult.error)}
`);
`, "signalPatchTypeError");
return;
}
// Don't use the parsed value, as it loses the substructure identities
Expand All @@ -342,6 +374,7 @@ export class ClientPort<
if (openSignalSubscription === undefined) {
this.communicationWarning(
`Received signalError for unknown signal, subscribeId = ${message.subscribeId}`,
"signalUnknown",
);
return;
}
Expand Down Expand Up @@ -384,7 +417,7 @@ export class ClientPort<
patches = ${JSON.stringify(patches, null, 2)}.

Error: ${String(error)}
`);
`, "writableSignalPatchApplyError");
}
const parseResult = openSignalSubscription.endpoint.signalData.safeParse(afterValue);
if (!parseResult.success) {
Expand All @@ -400,7 +433,7 @@ export class ClientPort<
Zod error:

${Validator.prettyPrintZod("value", parseResult.error)}
`);
`, "writableSignalPatchTypeError");
return;
}
// Don't use the parsed value, as it loses the substructure identities
Expand All @@ -415,6 +448,7 @@ export class ClientPort<
if (openSignalSubscription === undefined) {
this.communicationWarning(
`Received writableSignalError for unknown signal, subscribeId = ${message.subscribeId}`,
"writableSignalUnknown",
);
return;
}
Expand All @@ -431,14 +465,33 @@ export class ClientPort<
private receivedCommunicationWarning(
message: ServerToClientMessage & { type: "communicationWarning" },
) {
this.logger.warnText`
Received communication warning from the server: ${message.warning}

This is usually caused by communication protocol incompatibility. Please make sure you are
using the up-to-date versions of the SDK and LM Studio.

Note: This warning was received from the server and is printed on the client for convenience.
`;
const kind = normalizeCommunicationWarningKind(message.kind);
if (this.onCommunicationWarning === undefined) {
this.logger.warnText`
Received communication warning from the server (${kind}): ${message.warning}

This is usually caused by communication protocol incompatibility. Please make sure you are
using the up-to-date versions of the SDK and LM Studio.

Note: This warning was received from the server and is printed on the client for convenience.
`;
}
this.reportCommunicationWarning({
direction: "received",
kind,
warning: message.warning,
});
}

private reportCommunicationWarning(communicationWarning: ClientPortCommunicationWarning): void {
if (this.onCommunicationWarning === undefined) {
return;
}
try {
this.onCommunicationWarning(communicationWarning);
} catch (error) {
this.logger.error("Error in onCommunicationWarning callback:", error);
}
}

private receivedKeepAliveAck(_message: ServerToClientMessage & { type: "keepAliveAck" }) {
Expand Down
2 changes: 1 addition & 1 deletion packages/lms-communication-client/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
export { AuthenticatedWsClientTransport } from "./AuthenticatedWsClientTransport.js";
export { ClientPort, InferClientPort } from "./ClientPort.js";
export { ClientPort, type ClientPortCommunicationWarning, InferClientPort } from "./ClientPort.js";
export { GenericClientTransport } from "./GenericClientTransport.js";
export { LMStudioHostedEnv, getHostedEnv } from "./LMStudioHostedEnv.js";
export { WsClientTransport } from "./WsClientTransport.js";
Loading