From 2042afd492bcdfc56183fcb9b705eb1c06d28b39 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Fri, 17 Oct 2025 18:38:55 +0300 Subject: [PATCH 1/7] add sdk internal logging PoC --- src/server/streamableHttp.ts | 9 +++++++ src/shared/logger.ts | 52 ++++++++++++++++++++++++++++++++++++ src/shared/protocol.ts | 9 +++++++ 3 files changed, 70 insertions(+) create mode 100644 src/shared/logger.ts diff --git a/src/server/streamableHttp.ts b/src/server/streamableHttp.ts index d57e75cd7..7d551d97a 100644 --- a/src/server/streamableHttp.ts +++ b/src/server/streamableHttp.ts @@ -17,6 +17,7 @@ import getRawBody from 'raw-body'; import contentType from 'content-type'; import { randomUUID } from 'node:crypto'; import { AuthInfo } from './auth/types.js'; +import { consoleLogger, Logger } from '../shared/logger.js'; const MAXIMUM_MESSAGE_SIZE = '4mb'; @@ -108,6 +109,11 @@ export interface StreamableHTTPServerTransportOptions { * Default is false for backwards compatibility. */ enableDnsRebindingProtection?: boolean; + + /** + * A custom logger to use for SDK internal logs. + */ + logger?: Logger; } /** @@ -160,6 +166,7 @@ export class StreamableHTTPServerTransport implements Transport { private _allowedHosts?: string[]; private _allowedOrigins?: string[]; private _enableDnsRebindingProtection: boolean; + private _logger: Logger; sessionId?: string; onclose?: () => void; @@ -175,6 +182,7 @@ export class StreamableHTTPServerTransport implements Transport { this._allowedHosts = options.allowedHosts; this._allowedOrigins = options.allowedOrigins; this._enableDnsRebindingProtection = options.enableDnsRebindingProtection ?? false; + this._logger = options.logger ?? consoleLogger; } /** @@ -727,6 +735,7 @@ export class StreamableHTTPServerTransport implements Transport { const standaloneSse = this._streamMapping.get(this._standaloneSseStreamId); if (standaloneSse === undefined) { // The spec says the server MAY send messages on the stream, so it's ok to discard if no stream + this._logger.warning(`No standalone SSE stream found, discarding message: ${message.method}`); return; } diff --git a/src/shared/logger.ts b/src/shared/logger.ts new file mode 100644 index 000000000..1871e1f97 --- /dev/null +++ b/src/shared/logger.ts @@ -0,0 +1,52 @@ +/** + * Logger - SysLog RFC5424 compliant logger interface + * + * @remarks + * RFC5424: severity of all levels is assumed to be numerically ascending from most important to least important. + * RFC5424: https://tools.ietf.org/html/rfc5424 + * + */ + +type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'; + +export type Logger = { + [Level in LogLevel]: (message: string, extra?: Record) => void; +}; + +/** + * Console logger implementation of the Logger interface, to be used by default if no custom logger is provided. + * + * @remarks + * The console logger will log to the console. + * + * The console logger will log at the following levels: + * - log (alias for console.debug) + * - info + * - error + */ +export const consoleLogger: Logger = { + debug: (message, extra) => { + console.log(message, extra); + }, + info: (message, extra) => { + console.info(message, extra); + }, + notice: (message, extra) => { + console.info(message, extra); + }, + warning: (message, extra) => { + console.warn(message, extra); + }, + error: (message, extra) => { + console.error(message, extra); + }, + critical: (message, extra) => { + console.error(message, extra); + }, + alert: (message, extra) => { + console.error(message, extra); + }, + emergency: (message, extra) => { + console.error(message, extra); + }, +}; \ No newline at end of file diff --git a/src/shared/protocol.ts b/src/shared/protocol.ts index 5cb969418..e9f73f318 100644 --- a/src/shared/protocol.ts +++ b/src/shared/protocol.ts @@ -27,6 +27,7 @@ import { } from '../types.js'; import { Transport, TransportSendOptions } from './transport.js'; import { AuthInfo } from '../server/auth/types.js'; +import { consoleLogger, Logger } from './logger.js'; /** * Callback for progress notifications. @@ -52,6 +53,11 @@ export type ProtocolOptions = { * e.g., ['notifications/tools/list_changed'] */ debouncedNotificationMethods?: string[]; + + /** + * A custom logger to use for SDK internal logs. + */ + logger?: Logger; }; /** @@ -184,6 +190,7 @@ export abstract class Protocol = new Map(); private _timeoutInfo: Map = new Map(); private _pendingDebouncedNotifications = new Set(); + private readonly _logger: Logger; /** * Callback for when the connection is closed for any reason. @@ -210,7 +217,9 @@ export abstract class Protocol Promise; constructor(private _options?: ProtocolOptions) { + this._logger = _options?.logger ?? consoleLogger; this.setNotificationHandler(CancelledNotificationSchema, notification => { + this._logger.debug('Received a cancelled notification', { notification }); const controller = this._requestHandlerAbortControllers.get(notification.params.requestId); controller?.abort(notification.params.reason); }); From a78b8668291d5271d7f6e78e1b6fa4dcfd781bd0 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Fri, 17 Oct 2025 18:50:53 +0300 Subject: [PATCH 2/7] fix comment --- src/shared/logger.ts | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/shared/logger.ts b/src/shared/logger.ts index 1871e1f97..1a3015c12 100644 --- a/src/shared/logger.ts +++ b/src/shared/logger.ts @@ -1,14 +1,12 @@ -/** - * Logger - SysLog RFC5424 compliant logger interface - * - * @remarks - * RFC5424: severity of all levels is assumed to be numerically ascending from most important to least important. - * RFC5424: https://tools.ietf.org/html/rfc5424 - * - */ + type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'; +/** + * Logger - SysLog RFC5424 compliant logger interface + * + * @see RFC5424: https://tools.ietf.org/html/rfc5424 + */ export type Logger = { [Level in LogLevel]: (message: string, extra?: Record) => void; }; From d216768abada995326ac7e90d254e62b474f14c7 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Fri, 17 Oct 2025 18:51:23 +0300 Subject: [PATCH 3/7] fix comment --- src/shared/logger.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/shared/logger.ts b/src/shared/logger.ts index 1a3015c12..4ecba9b15 100644 --- a/src/shared/logger.ts +++ b/src/shared/logger.ts @@ -3,7 +3,7 @@ type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'; /** - * Logger - SysLog RFC5424 compliant logger interface + * Logger - SysLog RFC5424 compliant logger type * * @see RFC5424: https://tools.ietf.org/html/rfc5424 */ From 752199106920c9bb60fefa5fe0f460839f8096bf Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Fri, 17 Oct 2025 18:53:16 +0300 Subject: [PATCH 4/7] fix comment --- src/shared/logger.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/shared/logger.ts b/src/shared/logger.ts index 4ecba9b15..6f2194656 100644 --- a/src/shared/logger.ts +++ b/src/shared/logger.ts @@ -1,5 +1,8 @@ - - +/** + * LogLevel - SysLog RFC5424 compliant log levels + * + * @see RFC5424: https://tools.ietf.org/html/rfc5424 + */ type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'; /** From 3d7aca72d4ceac30808a6d2fbaa1a3b1376e57e5 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Fri, 17 Oct 2025 18:55:09 +0300 Subject: [PATCH 5/7] prettier --- src/shared/logger.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/shared/logger.ts b/src/shared/logger.ts index 6f2194656..c625d902b 100644 --- a/src/shared/logger.ts +++ b/src/shared/logger.ts @@ -1,13 +1,13 @@ /** * LogLevel - SysLog RFC5424 compliant log levels - * + * * @see RFC5424: https://tools.ietf.org/html/rfc5424 */ type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'; /** * Logger - SysLog RFC5424 compliant logger type - * + * * @see RFC5424: https://tools.ietf.org/html/rfc5424 */ export type Logger = { @@ -49,5 +49,5 @@ export const consoleLogger: Logger = { }, emergency: (message, extra) => { console.error(message, extra); - }, -}; \ No newline at end of file + } +}; From cb948fb18fe0c0365bb59c509846533af6cae5d1 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Sat, 18 Oct 2025 20:37:11 +0300 Subject: [PATCH 6/7] refactor to use syslog numbering of severity --- src/shared/logger.ts | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/src/shared/logger.ts b/src/shared/logger.ts index c625d902b..2eeaaaabf 100644 --- a/src/shared/logger.ts +++ b/src/shared/logger.ts @@ -3,7 +3,27 @@ * * @see RFC5424: https://tools.ietf.org/html/rfc5424 */ -type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency'; +export interface LogLevels { + emerg: number; + alert: number; + crit: number; + error: number; + warning: number; + notice: number; + info: number; + debug: number; + } + +export const LogLevels: LogLevels = { + emerg: 0, + alert: 1, + crit: 2, + error: 3, + warning: 4, + notice: 5, + info: 6, + debug: 7 + }; /** * Logger - SysLog RFC5424 compliant logger type @@ -11,7 +31,7 @@ type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | * @see RFC5424: https://tools.ietf.org/html/rfc5424 */ export type Logger = { - [Level in LogLevel]: (message: string, extra?: Record) => void; + [Level in keyof LogLevels]: (message: string, extra?: Record) => void; }; /** @@ -41,13 +61,13 @@ export const consoleLogger: Logger = { error: (message, extra) => { console.error(message, extra); }, - critical: (message, extra) => { + crit: (message, extra) => { console.error(message, extra); }, alert: (message, extra) => { console.error(message, extra); }, - emergency: (message, extra) => { + emerg: (message, extra) => { console.error(message, extra); } }; From 92b9c3ca53931a3783872f8dec24c68eaac84da0 Mon Sep 17 00:00:00 2001 From: Konstantin Konstantinov Date: Sat, 18 Oct 2025 20:45:47 +0300 Subject: [PATCH 7/7] prettier --- src/shared/logger.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/shared/logger.ts b/src/shared/logger.ts index 2eeaaaabf..306c0b40e 100644 --- a/src/shared/logger.ts +++ b/src/shared/logger.ts @@ -12,7 +12,7 @@ export interface LogLevels { notice: number; info: number; debug: number; - } +} export const LogLevels: LogLevels = { emerg: 0, @@ -23,7 +23,7 @@ export const LogLevels: LogLevels = { notice: 5, info: 6, debug: 7 - }; +}; /** * Logger - SysLog RFC5424 compliant logger type