Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { match, P } from 'ts-pattern';
import { platformWebSocketFactory } from '../platform/factory';
import type { MinimalWebSocket } from '../platform/minimal-websocket';
import type { Backoff } from './backoff/backoff';
import type { WebsocketBuffer } from './websocket-buffer';
import { WebsocketConnectionState } from './websocket-connection-state';
import {
type HeartbeatEventDetail,
type HeartbeatMissedEventDetail,
type ReconnectEventDetail,
type RetryEventDetail,
type UrlResolvedEventDetail,
WebsocketEvent,
type WebsocketEventListener,
type WebsocketEventListenerOptions,
type WebsocketEventListeners,
type WebsocketEventListenerWithOptions,
type WebsocketEventMap,
type WebsocketEventUnion,
} from './websocket-event';
import { isRequiredHeartbeatOptions } from './websocket-heartbeat-options';
import type { WebsocketOptions } from './websocket-options';
import {
deserializeIfNeeded,
serializeIfNeeded,
type WebsocketData,
} from './websocket-serializer';
import {
isString,
resolveUrl,
type UrlResolver,
} from './websocket-url-resolver';
/** Frame shape for the deserialize-failure log, without reading the bytes. */
function describeFrameData(data: unknown): string {
if (typeof data === 'string') return `string of ${data.length} chars`;
if (data instanceof ArrayBuffer)
return `ArrayBuffer of ${data.byteLength} bytes`;
if (typeof Blob !== 'undefined' && data instanceof Blob) {
return `Blob of ${data.size} bytes`;
}
if (ArrayBuffer.isView(data)) {
return `${data.constructor.name} of ${data.byteLength} bytes`;
}
return typeof data;
}
/** Strips the query (auth tokens live there) so the URL is safe to log. */
function redactUrl(url: string): string {
const queryStart = url.indexOf('?');
return queryStart === -1 ? url : url.slice(0, queryStart);
}
/**
* A websocket wrapper that can be configured to reconnect automatically and buffer messages when the websocket is not connected.
*/
export class Websocket<Send = WebsocketData, Receive = WebsocketData> {
private _url!: string; // assigned before the first socket opens
private readonly _urlResolver: UrlResolver; // the url resolver to use
private readonly _protocols?: string | string[]; // the protocols to use
private _binaryType?: BinaryType = 'blob'; // the binaryType to use
private _closedByUser: boolean = false; // whether the websocket was closed by the user
private connectionGeneration = 0;
private _lastConnection?: Date; // timestamp of the last connection
private _underlyingWebsocket!: MinimalWebSocket; // assigned by tryConnect
private connectPending: boolean = false; // whether tryConnect is resolving its url / creating a socket
private retryTimeout?: ReturnType<typeof globalThis.setTimeout>; // timeout for the next retry, if any
private heartbeatInterval?: ReturnType<typeof setInterval> | undefined; // interval for the heartbeat
private heartbeatTimeout?: ReturnType<typeof setTimeout> | undefined; // timeout for the heartbeat
private missedHeartbeats: number = 0; // number of missed heartbeats
connectionState: WebsocketConnectionState =
WebsocketConnectionState.Connecting;
private _options: WebsocketOptions<Send, Receive> &
Required<Pick<WebsocketOptions<Send, Receive>, 'listeners' | 'retry'>>; // options/config for the websocket
/**
* Creates a new websocket.
*
* @param url to connect to.
* @param protocols optional protocols to use.
* @param options optional options to use.
*/
constructor(
resolver: UrlResolver,
protocols?: string | string[],
options?: WebsocketOptions<Send, Receive>
) {
this._protocols = protocols;
// make a copy of the options to prevent the user from changing them
this._options = {
buffer: options?.buffer,
retry: {
maxRetries: options?.retry?.maxRetries,
instantReconnect: options?.retry?.instantReconnect,
backoff: options?.retry?.backoff,
},
heartbeat: {
timeout: options?.heartbeat?.timeout,
interval: options?.heartbeat?.interval,
pingMessage: options?.heartbeat?.pingMessage,
pongMessage: options?.heartbeat?.pongMessage,
maxMissedHeartbeats: options?.heartbeat?.maxMissedHeartbeats,
},
listeners: {
open: [...(options?.listeners?.open ?? [])],
close: [...(options?.listeners?.close ?? [])],
error: [...(options?.listeners?.error ?? [])],
message: [...(options?.listeners?.message ?? [])],
retry: [...(options?.listeners?.retry ?? [])],
reconnect: [...(options?.listeners?.reconnect ?? [])],
heartbeatSent: [...(options?.listeners?.heartbeatSent ?? [])],
heartbeatReceived: [...(options?.listeners?.heartbeatReceived ?? [])],
heartbeatMissed: [...(options?.listeners?.heartbeatMissed ?? [])],
urlResolved: [...(options?.listeners?.urlResolved ?? [])],
},
binaryType: options?.binaryType,
serializer: options?.serializer,
factory: options?.factory,
};
if (options?.binaryType !== undefined) {
this.binaryType = options.binaryType;
}
this._urlResolver = resolver;
if (isString(resolver)) {
this._url = resolver;
}
this._closedByUser = options?.autoConnect === false;
if (this._closedByUser) {
this.connectionState = WebsocketConnectionState.Closed;
} else {
this.tryConnect();
}
}
/**
* Getter for the url.
*
* @return the url.
*/
get url(): string {
return this._url;
}
/**
* Getter for the protocols.
*
* @return the protocols, or undefined if none were provided.
*/
get protocols(): string | string[] | undefined {
return this._protocols;
}
/**
* Getter for the buffer.
*
* @return the buffer, or undefined if none was provided.
*/
get buffer(): WebsocketBuffer<Send> | undefined {
return this._options.buffer;
}
/**
* Getter for the maxRetries.
*
* @return the maxRetries, or undefined if none was provided (no limit).
*/
get maxRetries(): number | undefined {
return this._options.retry.maxRetries;
}
/**
* Getter for the instantReconnect.
*
* @return the instantReconnect, or undefined if none was provided.
*/
get instantReconnect(): boolean | undefined {
return this._options.retry.instantReconnect;
}
/**
* Getter for the backoff.
*
* @return the backoff, or undefined if none was provided.
*/
get backoff(): Backoff | undefined {
return this._options.retry.backoff;
}
/**
* Whether the websocket was closed by the user. A websocket is closed by the user by calling close().
*
* @return true if the websocket was closed by the user, false otherwise.
*/
get closedByUser(): boolean {
return this._closedByUser;
}
/**
* Getter for the last 'open' event, e.g. the last time the websocket was connected.
*
* @return the last 'open' event, or undefined if the websocket was never connected.
*/
get lastConnection(): Date | undefined {
return this._lastConnection;
}
/**
* Getter for the underlying websocket. This can be used to access the browser's native websocket directly.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
* @return the underlying websocket.
*/
get underlyingWebsocket(): MinimalWebSocket {
return this._underlyingWebsocket;
}
/**
* Getter for the readyState of the underlying websocket.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState
* @return the readyState of the underlying websocket.
*/
get readyState(): number {
return (
this._underlyingWebsocket?.readyState ??
(this.closedByUser
? WebsocketConnectionState.Closed
: WebsocketConnectionState.Connecting)
);
}
/**
* Getter for the bufferedAmount of the underlying websocket.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/bufferedAmount
* @return the bufferedAmount of the underlying websocket.
*/
get bufferedAmount(): number {
return this._underlyingWebsocket?.bufferedAmount ?? 0;
}
/**
* Getter for the extensions of the underlying websocket.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/extensions
* @return the extensions of the underlying websocket.
*/
get extensions(): string {
return this._underlyingWebsocket?.extensions ?? '';
}
/**
* Getter for the binaryType of the underlying websocket.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType
* @return the binaryType of the underlying websocket.
*/
get binaryType(): BinaryType {
return this._binaryType ?? this._underlyingWebsocket.binaryType;
}
/**
* Setter for the binaryType of the underlying websocket.
*
* @param value to set, 'blob' or 'arraybuffer'.
*/
set binaryType(value: BinaryType) {
if (this._underlyingWebsocket) {
this._underlyingWebsocket.binaryType = value;
}
this._binaryType = value;
}
/**
* Sends data over the websocket.
*
* If the websocket is not connected and a buffer was provided on creation, the data will be added to the buffer.
* If no buffer was provided or the websocket was closed by the user, the data will be dropped.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
* @param data to send.
*/
public send(rawData: Send): boolean {
if (this.closedByUser) return false; // no-op if closed by user
let data = serializeIfNeeded(rawData, this._options.serializer);
if (
this._underlyingWebsocket &&
this._underlyingWebsocket.readyState === this._underlyingWebsocket.OPEN
) {
this._underlyingWebsocket.send(data); // websocket is connected, send data
return true;
} else if (this.buffer !== undefined) {
this.buffer.add(rawData); // websocket is not connected, add data to buffer
}
return false;
}
/**
* Close the websocket. No connection-retry will be attempted after this.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close
* @param code optional close code.
* @param reason optional close reason.
*/
public close(code?: number, reason?: string): void {
this.cancelScheduledConnectionRetry(); // cancel any scheduled retries
this._closedByUser = true; // mark websocket as closed by user
this.connectionGeneration++;
// The underlying websocket is unassigned while the first connect attempt
// is still resolving its url; tryConnect observes _closedByUser and
// won't open a socket after this point.
(this._underlyingWebsocket as MinimalWebSocket | undefined)?.close(
code,
reason
);
this.stopHeartbeat();
}
/**
* Adds an event listener for the given event-type.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
* @param type of the event to add the listener for.
* @param listener to add.
* @param options to use when adding the listener.
*/
public addEventListener<K extends WebsocketEvent>(
type: K,
listener: WebsocketEventListener<K, Send, Receive>,
options?: WebsocketEventListenerOptions
): void {
this._options.listeners[type].push({ listener, options }); // add listener to list of listeners
}
/**
* Removes one or more event listener for the given event-type that match the given listener and options.
*
* @param type of the event to remove the listener for.
* @param listener to remove.
* @param options that were used when the listener was added.
*/
public removeEventListener<K extends WebsocketEvent>(
type: K,
listener: WebsocketEventListener<K, Send, Receive>,
options?: WebsocketEventListenerOptions
): void {
const isListenerNotToBeRemoved = (
l: WebsocketEventListenerWithOptions<K, Send, Receive>
) => l.listener !== listener || l.options !== options;
(this._options.listeners[type] as WebsocketEventListenerWithOptions<
K,
Send,
Receive
>[]) = this._options.listeners[type].filter(isListenerNotToBeRemoved); // only keep listeners that are not to be removed
}
/**
* Creates a new browser-native websocket and connects it to the given URL with the given protocols
* and adds all event listeners to the browser-native websocket.
*/
private async tryConnect(): Promise<void> {
this.connectPending = true;
const generation = this.connectionGeneration;
try {
const url = await resolveUrl(this._urlResolver);
// The websocket may have been closed by the user while the url was
// resolving (e.g. a token fetch); don't open a connection nobody owns.
if (this._closedByUser || generation !== this.connectionGeneration) {
return;
}
this._url = url;
const event = new CustomEvent<UrlResolvedEventDetail>(
WebsocketEvent.UrlResolved,
{
detail: {
url: this._url,
},
}
);
this.dispatchEvent(WebsocketEvent.UrlResolved, event);
// Listeners may close or replace the session synchronously.
if (this._closedByUser || generation !== this.connectionGeneration) {
return;
}
const factory = this._options.factory ?? platformWebSocketFactory;
const newSocket = factory(this.url, this.protocols); // create new browser-native websocket and add all event listeners
this._underlyingWebsocket = newSocket;
this._underlyingWebsocket.addEventListener(
WebsocketEvent.Open,
this.handleOpenEvent
);
this._underlyingWebsocket.addEventListener(
WebsocketEvent.Close,
this.handleCloseEvent
);
this._underlyingWebsocket.addEventListener(
WebsocketEvent.Error,
this.handleErrorEvent
);
this._underlyingWebsocket.addEventListener(
WebsocketEvent.Message,
this.handleMessageEvent
);
if (this.binaryType !== undefined) {
this._underlyingWebsocket.binaryType = this.binaryType;
}
} catch {
// URL resolution can require online authorization. No native socket
// exists to emit a close event when that fails, so retry it here too.
if (!this._closedByUser && generation === this.connectionGeneration) {
this.connectionState = WebsocketConnectionState.Closed;
this.dispatchEvent(WebsocketEvent.Error, new Event('error'));
this.scheduleConnectionRetryIfNeeded();
}
} finally {
this.connectPending = false;
// A close followed by reconnect may be a different signed-in session.
// Resolve fresh credentials instead of adopting the previous URL.
if (!this._closedByUser && generation !== this.connectionGeneration) {
this.tryConnect();
}
}
}
/**
* Removes all event listeners from the browser-native websocket and closes it.
*/
private clearWebsocket() {
// Nothing to clear while the first connection attempt is still resolving
// its url (the underlying websocket is only assigned in tryConnect).
if (!this._underlyingWebsocket) {
return;
}
this._underlyingWebsocket.removeEventListener(
WebsocketEvent.Open,
this.handleOpenEvent
);
this._underlyingWebsocket.removeEventListener(
WebsocketEvent.Close,
this.handleCloseEvent
);
this._underlyingWebsocket.removeEventListener(
WebsocketEvent.Error,
this.handleErrorEvent
);
this._underlyingWebsocket.removeEventListener(
WebsocketEvent.Message,
this.handleMessageEvent
);
// Only close if the connection is OPEN or CLOSING
// The ws library throws an error when closing a CONNECTING WebSocket
const readyState = this._underlyingWebsocket.readyState;
if (readyState === WebSocket.CONNECTING) {
// Close the abandoned attempt once it opens so it doesn't linger
// half-connected on the server.
const abandoned = this._underlyingWebsocket;
abandoned.addEventListener(WebsocketEvent.Open, () => abandoned.close(), {
once: true,
});
} else if (readyState !== WebSocket.CLOSED) {
this._underlyingWebsocket.close();
}
}
/**
* Handles the 'open' event of the browser-native websocket.
* @param event to handle.
*/
private handleOpenEvent = (event: Event) =>
this.handleEvent(WebsocketEvent.Open, event);
/**
* Handles the 'error' event of the browser-native websocket.
* @param event to handle.
*/
private handleErrorEvent = (event: Event) =>
this.handleEvent(WebsocketEvent.Error, event);
/**
* Handles the 'close' event of the browser-native websocket.
* @param event to handle.
*/
private handleCloseEvent = (event: CloseEvent) =>
this.handleEvent(WebsocketEvent.Close, event);
private handleHeartbeatReceived = (event: MessageEvent) => {
if (this.heartbeatTimeout) {
clearTimeout(this.heartbeatTimeout);
this.heartbeatTimeout = undefined;
}
// A pong proves the connection is alive; only consecutive misses should
// count towards maxMissedHeartbeats.
this.missedHeartbeats = 0;
const receivedHeartbeatEvent = new CustomEvent<HeartbeatEventDetail>(
WebsocketEvent.HeartbeatReceived,
{
detail: {
message: event.data,
timestamp: Date.now(),
},
}
);
this.dispatchEvent(
WebsocketEvent.HeartbeatReceived,
receivedHeartbeatEvent
);
};
/**
* Handles the 'message' event of the browser-native websocket.
* @param event to handle.
*/
private handleMessageEvent = (event: MessageEvent) => {
if (event.data === this._options.heartbeat?.pongMessage) {
this.handleHeartbeatReceived(event);
return;
}
this.handleEvent(WebsocketEvent.Message, event);
};
/**
* Dispatch an event to all listeners of the given event-type.
*
* @param type of the event to dispatch.
* @param event to dispatch.
*/
private dispatchEvent<K extends WebsocketEvent>(
type: K,
event: WebsocketEventMap<Receive>[K]
) {
const eventListeners: WebsocketEventListeners<Send, Receive>[K] =
this._options.listeners[type];
const newEventListeners: WebsocketEventListeners<Send, Receive>[K] = [];
eventListeners.forEach(({ listener, options }) => {
listener(this, event); // invoke listener with event
if (
options === undefined ||
options.once === undefined ||
!options.once
) {
newEventListeners.push({ listener, options }); // only keep listener if it isn't a once-listener
}
});
this._options.listeners[type] = newEventListeners; // replace old listeners with new listeners that don't include once-listeners
}
/**
* Handles the given event by dispatching it to all listeners of the given event-type.
*
* @param type of the event to handle.
* @param event to handle.
*/
private handleEvent(
type: WebsocketEvent,
event: WebsocketEventMap<WebsocketData>[WebsocketEvent]
) {
const eventWithType = {
event,
type,
// Internal event handles have not yet deserialized the data
// thus here it is WebsocketData and not Receive
} as WebsocketEventUnion<WebsocketData>;
match(eventWithType)
.with({ type: WebsocketEvent.Close }, () => {
this.stopHeartbeat();
this.connectionState = WebsocketConnectionState.Closed;
this.dispatchEvent(type, event);
this.scheduleConnectionRetryIfNeeded();
})
.with({ type: WebsocketEvent.Open }, () => {
// Set connection state to Open first, before any other actions that depend on it.
// This ensures startHeartbeat() can check state correctly.
this.connectionState = WebsocketConnectionState.Open;
// Check if this is a reconnection (we had connected before)
if (this.backoff !== undefined && this._lastConnection !== undefined) {
const detail: ReconnectEventDetail = {
retries: this.backoff.retries,
lastConnection: new Date(this._lastConnection),
url: this._url,
};
const reconnectEvent = new CustomEvent<ReconnectEventDetail>(
WebsocketEvent.Reconnect,
{ detail }
);
this.dispatchEvent(WebsocketEvent.Reconnect, reconnectEvent);
}
// Reset on every successful open (not only on reconnects), otherwise
// retries spent establishing the first connection permanently eat
// into the maxRetries budget.
this.backoff?.reset();
if (
this._options.heartbeat &&
this._options.heartbeat.autoStart !== false
) {
this.startHeartbeat();
}
// Update lastConnection AFTER reconnect check, so we can detect first connect vs reconnect
this._lastConnection = new Date();
this.dispatchEvent(type, event);
this.sendBufferedData();
})
.with({ type: WebsocketEvent.retry }, () => {
this.connectionState = WebsocketConnectionState.Reconnecting;
this.dispatchEvent(type, event);
this.clearWebsocket();
this.tryConnect();
})
.with({ type: WebsocketEvent.Error }, () => {
this.connectionState = WebsocketConnectionState.Closing;
this.dispatchEvent(type, event);
})
.with({ type: WebsocketEvent.Message }, ({ event }) => {
let data: Receive | WebsocketData;
try {
data = deserializeIfNeeded(event.data, this._options.serializer);
} catch (error) {
console.error(
`websocket: failed to deserialize incoming message (${describeFrameData(event.data)}) from ${redactUrl(this._url)}:`,
error
);
throw error;
}
// Copying origin/lastEventId/source can throw on runtimes with
// stricter Event internals (Cloudflare Workers): the accessors or the
// MessageEvent init validation reject non-browser shapes, and a throw
// here escapes into the native dispatch and errors out the socket.
// Consumers only read `data`, so fall back to a data-only event.
let newEvent: MessageEvent;
try {
newEvent = new MessageEvent('message', {
data,
origin: event.origin,
lastEventId: event.lastEventId,
source: event.source,
});
} catch {
newEvent = new MessageEvent('message', { data });
}
this.dispatchEvent(WebsocketEvent.Message, newEvent);
})
.with(
{
type: P.union(
WebsocketEvent.Reconnect,
WebsocketEvent.HeartbeatSent,
WebsocketEvent.HeartbeatReceived,
WebsocketEvent.HeartbeatMissed
),
},
() => {
this.dispatchEvent(type, event);
}
)
.exhaustive(() => undefined);
}
/**
* Sends buffered data if there is a buffer defined.
*/
private sendBufferedData() {
if (this.buffer === undefined) {
return; // no buffer defined, nothing to send
}
for (
let ele = this.buffer.read();
ele !== undefined;
ele = this.buffer.read()
) {
this.send(ele); // send buffered data
}
}
/**
* Schedules a connection-retry if there is a backoff defined and the websocket was not closed by the user.
*/
private scheduleConnectionRetryIfNeeded() {
if (this.closedByUser) {
return; // user closed the websocket, no retry
}
if (this.backoff === undefined) {
return; // no backoff defined, no retry
}
this.cancelScheduledConnectionRetry();
// handler dispatches the retry event to all listeners of the retry event-type
const handleRetryEvent = (detail: RetryEventDetail) => {
const event: CustomEvent<RetryEventDetail> = new CustomEvent(
WebsocketEvent.retry,
{ detail }
);
this.handleEvent(WebsocketEvent.retry, event);
};
// create retry event detail, depending on the 'instantReconnect' option
const retryEventDetail: RetryEventDetail = {
backoff:
this._options.retry.instantReconnect === true ? 0 : this.backoff.next(),
retries:
this._options.retry.instantReconnect === true
? 0
: this.backoff.retries,
lastConnection: this._lastConnection,
url: this._url,
};
// schedule a new connection-retry if the maximum number of retries is not reached yet
if (
this._options.retry.maxRetries === undefined ||
retryEventDetail.retries <= this._options.retry.maxRetries
) {
this.retryTimeout = globalThis.setTimeout(
() => handleRetryEvent(retryEventDetail),
retryEventDetail.backoff
);
}
}
/**
* Cancels the scheduled connection-retry, if there is one.
*/
private cancelScheduledConnectionRetry() {
globalThis.clearTimeout(this.retryTimeout);
}
/**
* Handles the heartbeat timeout.
* If we don't receive a pong we will increment the missedHeartbeats counter and check if we should reconnect.
*/
private handleHeartbeatTimeout() {
this.missedHeartbeats++;
if (!isRequiredHeartbeatOptions(this._options?.heartbeat)) {
return;
}
const shouldReconnect =
this.missedHeartbeats > this._options.heartbeat.maxMissedHeartbeats;
const event = new CustomEvent<HeartbeatMissedEventDetail>(
WebsocketEvent.HeartbeatMissed,
{
detail: {
missedHeartbeats: this.missedHeartbeats,
willReconnect:
this.missedHeartbeats > this._options.heartbeat.maxMissedHeartbeats,
},
}
);
this.dispatchEvent(WebsocketEvent.HeartbeatMissed, event);
if (shouldReconnect) {
// Close the underlying websocket and trigger a reconnect
this._underlyingWebsocket.close(1000, 'No heartbeat received');
}
}
private isClosing(): boolean {
return (
this._underlyingWebsocket.readyState === this._underlyingWebsocket.CLOSING
);
}
/**
* Sends a heartbeat message to the websocket.
* Schedules a timeout for `this._options.heartbeat.timeout` milliseconds.
* If we don't receive a pong we will increment the missedHeartbeats counter and check if we should reconnect.
*/
private sendHeartbeat() {
if (!this._underlyingWebsocket || this.closedByUser) return;
if (!isRequiredHeartbeatOptions(this._options?.heartbeat)) {
return;
}
if (
this.isClosing() ||
this._underlyingWebsocket.readyState === this._underlyingWebsocket.CLOSED
) {
this.handleEvent(
WebsocketEvent.Close,
new CloseEvent('closed websocket by heartbeat, already closing')
);
return;
}
this._underlyingWebsocket.send(this._options.heartbeat.pingMessage);
const event = new CustomEvent<HeartbeatEventDetail>(
WebsocketEvent.HeartbeatReceived,
{
detail: {
message: this._options.heartbeat.pingMessage,
timestamp: Date.now(),
},
}
);
this.dispatchEvent(WebsocketEvent.HeartbeatSent, event);
this.heartbeatTimeout = setTimeout(
() => this.handleHeartbeatTimeout(),
this._options.heartbeat.timeout
);
}
/** Returns whether the heartbeat is running. */
isHeartbeatRunning(): boolean {
return this.heartbeatInterval !== undefined;
}
/**
* Stops the heartbeat interval and timeout.
*/
private stopHeartbeat() {
if (this.heartbeatInterval) {
clearInterval(this.heartbeatInterval);
this.heartbeatInterval = undefined;
}
if (this.heartbeatTimeout) {
clearTimeout(this.heartbeatTimeout);
this.heartbeatTimeout = undefined;
}
this.missedHeartbeats = 0;
}
/**
* Starts a new heartbeat interval.
* Call this manually if you set `autoStart: false` in heartbeat options.
*
* Safe to call multiple times - will stop any existing heartbeat first.
* Safe to call on closed connections - will no-op if connection isn't open.
*/
public startHeartbeat() {
this.stopHeartbeat();
this.missedHeartbeats = 0;
if (!isRequiredHeartbeatOptions(this._options?.heartbeat)) {
return;
}
// Don't start heartbeat if connection isn't open - avoids orphan timers
if (this.connectionState !== WebsocketConnectionState.Open) {
return;
}
this.heartbeatInterval = setInterval(() => {
if (this.connectionState === WebsocketConnectionState.Open) {
this.sendHeartbeat();
}
}, this._options.heartbeat.interval);
}
/**
* Tears down the current underlying websocket and connects a fresh one.
*
* Unlike close(), this does NOT mark the websocket as closed by the user:
* send(), heartbeats and automatic retries keep working on the new
* connection.
*/
reconnect() {
// An explicit reconnect always overrides a prior user close — clear the
// flag before the pending check so a close() that landed while a connect
// attempt was resolving its url doesn't strand the instance. tryConnect
// discards an old generation's URL and resolves a fresh one when it settles.
this._closedByUser = false;
if (this.connectPending) {
// A fresh connection is already being established (e.g. 'online' and
// 'visibilitychange' firing together on wake) — starting a second
// tryConnect would orphan the first socket. An unchanged generation
// adopts this attempt; a closed generation retries with fresh credentials.
return;
}
this.cancelScheduledConnectionRetry();
this.stopHeartbeat();
this.clearWebsocket(); // detach listeners from (and close) the old socket
this.connectionState = WebsocketConnectionState.Reconnecting;
this.tryConnect();
}
/**
* Reconnects only if there is no usable connection: a no-op while the
* underlying websocket is OPEN, still CONNECTING, or a connect attempt is
* resolving its url, and a no-op after the user closed the websocket
* (only an explicit reconnect() may override a user close). Safe to call
* from connectivity signals like 'online' or 'visibilitychange' without
* disturbing a healthy connection.
*/
reconnectIfDisconnected() {
if (this.connectPending || this._closedByUser) {
return;
}
const readyState = (this._underlyingWebsocket as WebSocket | undefined)
?.readyState;
if (readyState === WebSocket.OPEN || readyState === WebSocket.CONNECTING) {
return;
}
this.reconnect();
}
}