@mastra/core1.85.061.9 kB
import { _ as NoopLeaseProvider, a as rehydrateError, c as RUN_LOG_TTL_MS, d as toCachedLogFrame, g as EventEmitterPubSub, h as withAck, i as withCaching, l as cachedLogTtlMs, n as PublisherQueueLimitError, o as serializeError, r as CachingPubSub, s as RUN_LOCAL_TOPIC_PREFIXES, t as DefaultStepResult, u as isRunLocalTopic, v as PubSub, y as isLeaseProvider } from "../output-helpers-D4II19No.js";
import { n as DefaultGeneratedFileWithType, t as DefaultGeneratedFile } from "../file-DGZrR5f7.js";
import { createHash } from "crypto";
import { basename, dirname, join, sep } from "path";
import { link, mkdir, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from "fs/promises";
import net from "net";
// src/events/codec/registry.ts
const classRegistry = /* @__PURE__ */ new Map();
function registerClass(name, codec) {
classRegistry.set(name, codec);
}
function getClassCodec(name) {
return classRegistry.get(name);
}
// src/events/codec/registrations.ts
/**
* Built-in class codecs.
*
* IMPORTANT: This module must be loaded for `instanceof` to survive
* serialization across the unix-socket pubsub. The `BUILTIN_CODECS_REGISTERED`
* constant exists solely so consumers can import it as a *named* import (see
* `codec.ts`). A `import './registrations'` side-effect import would be
* tree-shaken out of dist consumers because `packages/core/package.json` has
* `"sideEffects": false`. Named imports are kept by every bundler.
*
* `DefaultStepResult` flows through workflow output schemas typed as
* `z.any()`, so it crosses the unix-socket pubsub on the evented engine.
* Without a class registration, consumers that rely on
* `instanceof DefaultStepResult` (e.g. the in-memory storage path) would
* receive plain data. The generic `TOOLS` type parameter is erased at
* runtime, so we register the constructor name once.
*/
const BUILTIN_CODECS_REGISTERED = (() => {
registerClass("DefaultGeneratedFile", {
toData: (f) => ({
data: f.base64,
mediaType: f.mediaType
}),
fromData: (d) => new DefaultGeneratedFile({
data: d.data,
mediaType: d.mediaType
})
});
registerClass("DefaultGeneratedFileWithType", {
toData: (f) => ({
data: f.base64,
mediaType: f.mediaType
}),
fromData: (d) => new DefaultGeneratedFileWithType({
data: d.data,
mediaType: d.mediaType
})
});
registerClass("DefaultStepResult", {
toData: (s) => ({
content: s.content,
finishReason: s.finishReason,
usage: s.usage,
warnings: s.warnings,
request: s.request,
response: s.response,
providerMetadata: s.providerMetadata,
tripwire: s.tripwire
}),
fromData: (d) => new DefaultStepResult(d)
});
return true;
})();
// src/events/codec/tags.ts
/**
* Discriminator key for codec-tagged envelopes. Long, namespaced, and unlikely
* to collide with user data. Plain objects that happen to carry this key but
* do not match an envelope shape are preserved as-is by the decoder.
*
* **Reservation contract:** `__m_codec__` is reserved on the wire. Do not use
* it as a property name on user objects that cross the pubsub boundary — if
* the surrounding shape also happens to match an envelope (e.g.
* `{ __m_codec__: 'Date', v: '...' }`), the decoder will reconstruct it as
* the tagged type. The conservative shape check in `isEnvelope` keeps the
* blast radius narrow, and `toJSON()` is skipped for objects already carrying
* this key, but the safest path is to avoid the namespace entirely.
*/
const CODEC_TAG = "__m_codec__";
/**
* Returns true when `value` looks like a codec envelope. The check is
* conservative — an object with the tag key but an unknown tag value, or a
* shape that does not match any envelope variant, is treated as user data.
*/
function isEnvelope(value) {
const tag = value[CODEC_TAG];
if (typeof tag !== "string") return false;
switch (tag) {
case "Undefined": return true;
case "Date":
case "BigInt":
case "URL": return typeof value.v === "string";
case "RegExp": {
const v = value.v;
if (!v || typeof v.source !== "string" || typeof v.flags !== "string") return false;
if (v.source.length > 1024) return false;
return /^[dgimsuvy]*$/.test(v.flags) && new Set(v.flags).size === v.flags.length;
}
case "Map":
case "Set": return Array.isArray(value.v);
case "Error": return typeof value.v === "object" && value.v !== null;
case "Class": return typeof value.n === "string";
default: return false;
}
}
// src/events/codec/codec.ts
/**
* Encode a value into a JSON-safe shape. Non-JSON-safe types (Date, Error,
* Map, Set, RegExp, URL, BigInt, undefined, registered classes) are wrapped
* in tagged envelopes that the decoder can reconstruct.
*
* Functions and symbols are dropped (parity with JSON.stringify). Cycles are
* replaced with null at recurrence; shared (non-cyclic) references are encoded
* at every occurrence. NaN/Infinity become null. Honors
* user `toJSON()` methods on plain objects.
*/
function encode(value) {
if (!BUILTIN_CODECS_REGISTERED) throw new Error("Built-in codec registrations failed to load");
return walk(value, /* @__PURE__ */ new WeakSet());
}
function walk(v, seen) {
if (v === null || typeof v !== "object") return walkValue(v, seen);
if (seen.has(v)) return null;
seen.add(v);
try {
return walkValue(v, seen);
} finally {
seen.delete(v);
}
}
function walkValue(v, seen) {
if (v === void 0) return { [CODEC_TAG]: "Undefined" };
if (v === null) return null;
const t = typeof v;
if (t === "string" || t === "boolean") return v;
if (t === "number") return Number.isFinite(v) ? v : null;
if (t === "bigint") return {
[CODEC_TAG]: "BigInt",
v: v.toString()
};
if (t === "function" || t === "symbol") return void 0;
if (v instanceof Date) return {
[CODEC_TAG]: "Date",
v: v.toISOString()
};
if (v instanceof RegExp) return {
[CODEC_TAG]: "RegExp",
v: {
source: v.source,
flags: v.flags
}
};
if (v instanceof URL) return {
[CODEC_TAG]: "URL",
v: v.toString()
};
if (v instanceof Error) return {
[CODEC_TAG]: "Error",
v: serializeError(v)
};
if (v instanceof Map) {
const entries = [];
for (const [k, val] of v.entries()) entries.push([walk(k, seen), walk(val, seen)]);
return {
[CODEC_TAG]: "Map",
v: entries
};
}
if (v instanceof Set) {
const values = [];
for (const x of v) values.push(walk(x, seen));
return {
[CODEC_TAG]: "Set",
v: values
};
}
if (Array.isArray(v)) return v.map((x) => walk(x, seen));
if (t === "object") {
const maybeToJSON = v.toJSON;
if (typeof maybeToJSON === "function") return walk(maybeToJSON.call(v), seen);
const ctorName = v.constructor?.name;
if (ctorName && ctorName !== "Object") {
const reg = getClassCodec(ctorName);
if (reg) return {
[CODEC_TAG]: "Class",
n: ctorName,
v: walk(reg.toData(v), seen)
};
}
const out = {};
for (const k of Object.keys(v)) {
if (k === "__proto__") continue;
const raw = v[k];
if (raw === void 0) {
out[k] = { [CODEC_TAG]: "Undefined" };
continue;
}
const encoded = walk(raw, seen);
if (encoded === void 0) continue;
out[k] = encoded;
}
return out;
}
return v;
}
/**
* Reconstruct a `RegExp` from a decoded envelope payload. Re-validates the
* payload locally (independent of `isEnvelope`) so the constructor input is
* narrowed at this single call site: bounded `source` length, spec-defined
* flag whitelist, no duplicate flags. A malformed or hostile envelope yields
* an empty regex (`/(?:)/`) rather than throwing, keeping frame decoding
* resilient.
*
* NOTE: `source` is intentionally NOT escaped — a `RegExp` envelope's whole
* purpose is to round-trip a pattern, so metacharacters must reach
* `new RegExp(...)` verbatim. Safety comes from the bounded length, the
* flag whitelist, and the `try/catch` fallback, not from escaping.
*/
function decodeRegExpEnvelope(v) {
if (!v || typeof v !== "object") return /(?:)/;
const candidate = v;
if (typeof candidate.source !== "string") return /(?:)/;
if (typeof candidate.flags !== "string") return /(?:)/;
if (candidate.source.length > 1024) return /(?:)/;
const flags = candidate.flags;
if (!/^[dgimsuvy]*$/.test(flags)) return /(?:)/;
if (new Set(flags).size !== flags.length) return /(?:)/;
try {
return new RegExp(candidate.source, flags);
} catch {
return /(?:)/;
}
}
/**
* Decode a value previously produced by `encode`. Reconstructs envelope-tagged
* types and recursively decodes nested values. Plain objects that happen to
* carry a `CODEC_TAG` key but do not match an envelope shape are preserved.
*/
function decode(value) {
if (value === null) return null;
if (typeof value !== "object") return value;
if (Array.isArray(value)) return value.map(decode);
if ("__m_codec__" in value && isEnvelope(value)) {
const env = value;
switch (env[CODEC_TAG]) {
case "Undefined": return;
case "Date": return new Date(env.v);
case "BigInt": return BigInt(env.v);
case "RegExp": return decodeRegExpEnvelope(env.v);
case "URL": return new URL(env.v);
case "Map": return new Map(env.v.map(([k, val]) => [decode(k), decode(val)]));
case "Set": return new Set(env.v.map(decode));
case "Error": return rehydrateError(decodeSerializedError(env.v));
case "Class": {
const reg = getClassCodec(env.n);
const data = decode(env.v);
return reg ? reg.fromData(data) : data;
}
}
}
const out = {};
for (const k of Object.keys(value)) {
if (k === "__proto__") continue;
out[k] = decode(value[k]);
}
return out;
}
/**
* Recursively decode any envelopes embedded inside a SerializedError's custom
* fields (e.g. an error with a `details: Map` field). The top-level shape
* stays a SerializedError so `rehydrateError` can consume it.
*/
function decodeSerializedError(s) {
return decode(s);
}
// src/events/unix-socket-pubsub.ts
const DEFAULT_MAX_REMOTE_CLIENT_QUEUED_BYTES = 67108864;
const DEFAULT_MAX_PUBLISHER_QUEUED_BYTES = 67108864;
const DEFAULT_MAX_INBOUND_FRAME_BYTES = 67108864;
const DEFAULT_MEMBERSHIP_ACK_TIMEOUT_MS = 5e3;
const DEFAULT_BROKER_PATH_CHECK_INTERVAL_MS = 2e3;
const CONNECT_RETRY_DELAYS_MS = [
50,
100,
200
];
/** Longest bindable socket path in bytes (sun_path size). */
const MAX_SOCKET_PATH_BYTES = process.platform === "linux" ? 108 : 104;
const NEWLINE_BYTE = 10;
const LEASE_LOCK_RETRY_MS = 10;
const LEASE_RELEASE_CLOSE_GRACE_MS = 1e3;
const PROCESS_NONCE_KEY = Symbol.for("@mastra/core/unix-socket-pubsub/process-nonce");
const LEASE_RECOVERY_OWNERS_KEY = Symbol.for("@mastra/core/unix-socket-pubsub/lease-recovery-owners");
const processGlobals = globalThis;
const PROCESS_NONCE = processGlobals[PROCESS_NONCE_KEY] ??= globalThis.crypto.randomUUID();
const LIVE_LEASE_RECOVERY_OWNERS = processGlobals[LEASE_RECOVERY_OWNERS_KEY] ??= /* @__PURE__ */ new Set();
function leaseFileName(key) {
return createHash("sha256").update(key).digest("hex");
}
function delay(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
/** Returns the file identity at `path`, or undefined if nothing is there. */
async function fileIdentity(path) {
try {
const { dev, ino } = await stat(path);
return {
dev,
ino
};
} catch (error) {
if (error.code === "ENOENT") return void 0;
throw error;
}
}
function sameIdentity(a, b) {
return a !== void 0 && b !== void 0 && a.dev === b.dev && a.ino === b.ino;
}
function closeServer(server) {
return new Promise((resolve) => server.close(() => resolve()));
}
/**
* Max number of times a local subscriber callback may be redelivered after a
* nack. MUST be >= the consumer-side retry budget
* (`WorkflowEventProcessor.MAX_DELIVERY_ATTEMPTS`) — otherwise the transport
* gives up before the consumer can exhaust its budget and surface the terminal
* failure, which would leave the run silently hung.
*
* An invariant test in
* `packages/core/src/events/unix-socket-pubsub-redelivery-budget.test.ts`
* pins this ordering against the consumer constant so the two constants stay
* in sync as the consumer budget changes.
*/
const MAX_LOCAL_REDELIVERIES = 6;
const REDELIVERY_DELAY_MS = 100;
function serializeFrame(frame) {
return `${JSON.stringify(encode(frame))}\n`;
}
function writeSerializedFrame(socket, serializedFrame) {
return new Promise((resolve, reject) => {
let writeCompleted = false;
let drainCompleted = true;
let settled = false;
const cleanup = () => {
socket.off("error", onError);
socket.off("close", onClose);
socket.off("drain", onDrain);
};
const settle = (error) => {
if (settled) return;
settled = true;
cleanup();
if (error) {
reject(error);
return;
}
resolve();
};
const maybeResolve = () => {
if (writeCompleted && drainCompleted) settle();
};
const onError = (error) => settle(error);
const onClose = () => settle(/* @__PURE__ */ new Error("UnixSocketPubSub socket closed before write completed"));
const onDrain = () => {
drainCompleted = true;
maybeResolve();
};
socket.once("error", onError);
socket.once("close", onClose);
let drained;
try {
drained = socket.write(serializedFrame, (error) => {
if (error) {
settle(error);
return;
}
writeCompleted = true;
maybeResolve();
});
} catch (error) {
settle(error);
return;
}
if (!drained) {
drainCompleted = false;
socket.once("drain", onDrain);
}
});
}
/**
* Errors that mean the client's broker connection is gone. The string checks
* cover internal errors thrown from this file without an errno `code` — keep
* them in lockstep with those throw sites:
* - "socket closed before write completed" (writeSerializedFrame)
* - "broker connection closed" (#connectClient close handler)
* - "not connected to a broker" (#sendToActiveBroker)
*/
function isBrokerConnectionError(error) {
const code = error?.code;
if (code === "EPIPE" || code === "ECONNRESET" || code === "ENOTCONN" || code === "ERR_STREAM_DESTROYED") return true;
const message = error?.message;
return typeof message === "string" && (message.includes("socket closed before write completed") || message.includes("broker connection closed") || message.includes("not connected to a broker"));
}
function closedError(cause) {
return new Error("UnixSocketPubSub is closed", cause === void 0 ? void 0 : { cause });
}
function membershipKey(topic, group) {
return JSON.stringify([topic, group ?? null]);
}
function readFrames(socket, onFrame, maxFrameBytes) {
let pending = null;
let pendingBytes = 0;
const appendPending = (bytes) => {
const needed = pendingBytes + bytes.length;
if (!pending || pending.length < needed) {
const capacity = Math.min(maxFrameBytes, Math.max(needed, pending ? pending.length * 2 : 4096));
const grown = Buffer.allocUnsafe(capacity);
if (pending) pending.copy(grown, 0, 0, pendingBytes);
pending = grown;
}
bytes.copy(pending, pendingBytes);
pendingBytes = needed;
};
socket.on("data", (chunk) => {
if (socket.destroyed) return;
let offset = 0;
while (offset < chunk.length) {
const newlineIndex = chunk.indexOf(NEWLINE_BYTE, offset);
if (newlineIndex === -1) {
const rest = chunk.subarray(offset);
if (pendingBytes + rest.length > maxFrameBytes) {
pending = null;
pendingBytes = 0;
socket.destroy();
return;
}
appendPending(rest);
return;
}
const tail = chunk.subarray(offset, newlineIndex);
offset = newlineIndex + 1;
const lineBytes = pendingBytes + tail.length;
if (lineBytes > maxFrameBytes) {
pending = null;
pendingBytes = 0;
socket.destroy();
return;
}
const line = pending ? Buffer.concat([pending.subarray(0, pendingBytes), tail], lineBytes) : tail;
pending = null;
pendingBytes = 0;
const text = line.toString("utf8");
if (!text.trim()) continue;
try {
onFrame(decode(JSON.parse(text)));
} catch {}
if (socket.destroyed) return;
}
});
}
var UnixSocketPubSub = class extends PubSub {
socketPath;
#leaseDirectory;
#leaseMutationDirectory;
#leaseProcessDirectory;
#leaseRecoveryOwnerToken = globalThis.crypto.randomUUID();
#server;
/** File identity of the socket this broker bound, so it never removes or trusts a file it didn't create. */
#serverIdentity;
#brokerPathCheckTimer;
#brokerPathCheckIntervalMs;
#relinquishing;
#clientSocket;
#isBroker = false;
#closed = false;
#closedAt = 0;
#starting;
#subscriptions = /* @__PURE__ */ new Map();
#leavingSubscriptions = /* @__PURE__ */ new Set();
#localGroupCursors = /* @__PURE__ */ new Map();
#brokerGroupCursors = /* @__PURE__ */ new Map();
#subscribeWaiters = /* @__PURE__ */ new Map();
#unsubscribeWaiters = /* @__PURE__ */ new Map();
#brokerClients = /* @__PURE__ */ new Map();
#pendingWrites = /* @__PURE__ */ new Set();
#recovering;
#maxRemoteClientQueuedBytes;
#maxPublisherQueuedBytes;
#publisherQueuedBytes = 0;
#publisherCapacityWaiters = /* @__PURE__ */ new Set();
#maxInboundFrameBytes;
#membershipAckTimeoutMs;
#leaseDirectoriesReady;
#pendingLeaseOperations = /* @__PURE__ */ new Set();
constructor(socketPath, options = {}) {
super();
this.socketPath = socketPath;
this.#leaseDirectory = join(dirname(socketPath), "leases");
this.#leaseMutationDirectory = join(this.#leaseDirectory, "mutations");
this.#leaseProcessDirectory = join(this.#leaseDirectory, "processes");
LIVE_LEASE_RECOVERY_OWNERS.add(this.#leaseRecoveryOwnerToken);
this.#maxRemoteClientQueuedBytes = options.maxRemoteClientQueuedBytes ?? DEFAULT_MAX_REMOTE_CLIENT_QUEUED_BYTES;
const maxPublisherQueuedBytes = options.maxPublisherQueuedBytes ?? DEFAULT_MAX_PUBLISHER_QUEUED_BYTES;
if (!Number.isFinite(maxPublisherQueuedBytes) || maxPublisherQueuedBytes <= 0) throw new Error("UnixSocketPubSub maxPublisherQueuedBytes must be a positive finite number");
this.#maxPublisherQueuedBytes = maxPublisherQueuedBytes;
const maxInboundFrameBytes = options.maxInboundFrameBytes ?? DEFAULT_MAX_INBOUND_FRAME_BYTES;
if (!Number.isFinite(maxInboundFrameBytes) || maxInboundFrameBytes <= 0) throw new Error("UnixSocketPubSub maxInboundFrameBytes must be a positive finite number");
this.#maxInboundFrameBytes = maxInboundFrameBytes;
const membershipAckTimeoutMs = options.membershipAckTimeoutMs ?? DEFAULT_MEMBERSHIP_ACK_TIMEOUT_MS;
if (!Number.isFinite(membershipAckTimeoutMs) || membershipAckTimeoutMs <= 0) throw new Error("UnixSocketPubSub membershipAckTimeoutMs must be a positive finite number");
this.#membershipAckTimeoutMs = membershipAckTimeoutMs;
const brokerPathCheckIntervalMs = options.brokerPathCheckIntervalMs ?? DEFAULT_BROKER_PATH_CHECK_INTERVAL_MS;
if (!Number.isFinite(brokerPathCheckIntervalMs) || brokerPathCheckIntervalMs <= 0) throw new Error("UnixSocketPubSub brokerPathCheckIntervalMs must be a positive finite number");
this.#brokerPathCheckIntervalMs = brokerPathCheckIntervalMs;
}
get supportedModes() {
return ["push"];
}
/**
* A nack redelivers only to the subscriber that nacked. The broker keeps no
* pending list across processes, so a message a dead process held is lost.
*/
get redeliversUnacked() {
return false;
}
get isBroker() {
return this.#isBroker;
}
/** Number of remote clients currently connected to this broker. Always 0 for non-broker instances. */
get remoteClientCount() {
return this.#isBroker ? this.#brokerClients.size : 0;
}
/**
* Atomically acquires or renews a filesystem-backed lease shared by every
* UnixSocketPubSub instance in this socket directory.
*/
async acquireLease(key, owner, ttlMs) {
this.#throwIfClosed();
this.#validateLeaseTtl(ttlMs);
return this.#trackLeaseOperation(this.#withLeaseMutation(key, async (leasePath) => {
const existing = await this.#readLease(leasePath);
if (existing && await this.#isLeaseRecordLive(existing) && existing.owner !== owner) return {
acquired: false,
owner: existing.owner
};
await this.#writeLease(leasePath, owner, ttlMs);
return {
acquired: true,
owner
};
}));
}
/** Reads the current lease owner, reclaiming an expired or dead-process record. */
async getLeaseOwner(key) {
this.#throwIfClosed();
return this.#trackLeaseOperation(this.#withLeaseMutation(key, async (leasePath) => {
const existing = await this.#readLease(leasePath);
if (!existing) return void 0;
if (!await this.#isLeaseRecordLive(existing)) {
await unlink(leasePath).catch(() => {});
return;
}
return existing.owner;
}));
}
/**
* Releases the lease only when `owner` still matches the stored owner. A
* release that started before close() runs to completion (close() awaits it):
* shutdown fires releases and closes right after, and an aborted release
* leaves the lease file behind until another process notices the holder died.
*/
async releaseLease(key, owner) {
this.#throwIfClosed();
await this.#trackLeaseOperation(this.#withLeaseMutation(key, async (leasePath) => {
if ((await this.#readLease(leasePath))?.owner === owner) await unlink(leasePath).catch(() => {});
}, { finishAfterClose: true }));
}
/** Renews the lease only when it remains live and owned by `owner`. */
async renewLease(key, owner, ttlMs) {
this.#throwIfClosed();
this.#validateLeaseTtl(ttlMs);
return this.#trackLeaseOperation(this.#withLeaseMutation(key, async (leasePath) => {
const existing = await this.#readLease(leasePath);
if (!existing || !await this.#isLeaseRecordLive(existing) || existing.owner !== owner) return false;
await this.#writeLease(leasePath, owner, ttlMs);
return true;
}));
}
/**
* Transfers a live lease without leaving the key unowned. The owner check and
* replacement are serialized by the same per-key filesystem mutation lock.
*/
async transferLease(key, fromOwner, toOwner, ttlMs) {
this.#throwIfClosed();
this.#validateLeaseTtl(ttlMs);
return this.#trackLeaseOperation(this.#withLeaseMutation(key, async (leasePath) => {
const existing = await this.#readLease(leasePath);
if (!existing || !await this.#isLeaseRecordLive(existing) || existing.owner !== fromOwner) return false;
await this.#writeLease(leasePath, toOwner, ttlMs);
return true;
}));
}
async publish(topic, event, options) {
await this.#ensureStarted();
if (options?.localOnly) {
const localEvent = {
...event,
id: globalThis.crypto.randomUUID(),
createdAt: /* @__PURE__ */ new Date(),
deliveryAttempt: 1
};
this.#deliverLocal(topic, localEvent);
return;
}
if (this.#isBroker) {
await this.#publishFromBroker(topic, event, void 0, options?.localOnly);
return;
}
const socket = this.#clientSocket;
if (!socket || socket.destroyed) await this.#ensureStarted(true);
await this.#sendToBroker({
type: "publish",
topic,
event,
localOnly: options?.localOnly
});
}
async subscribe(topic, cb, options) {
const subscriptions = this.#subscriptions.get(topic) ?? /* @__PURE__ */ new Map();
const existing = subscriptions.get(cb);
if (existing && existing.group === options?.group) {
await this.#ensureStarted();
if (!this.#isBroker) await this.#waitForPendingMembershipAcknowledgement(this.#subscribeWaiters, membershipKey(topic, existing.group));
return;
}
if (existing) await this.unsubscribe(topic, cb);
const group = options?.group;
const hadMembership = this.#hasLocalMembership(topic, group);
const wasConnected = Boolean(this.#clientSocket && !this.#clientSocket.destroyed);
subscriptions.set(cb, {
callback: cb,
group
});
this.#subscriptions.set(topic, subscriptions);
try {
await this.#ensureStarted();
if (!this.#isBroker && wasConnected) {
if (hadMembership) await this.#waitForPendingMembershipAcknowledgement(this.#subscribeWaiters, membershipKey(topic, group));
else await this.#sendSubscribeToBroker(topic, group);
}
} catch (error) {
subscriptions.delete(cb);
if (subscriptions.size === 0) this.#subscriptions.delete(topic);
throw error;
}
}
async unsubscribe(topic, cb) {
const subscriptions = this.#subscriptions.get(topic);
const subscription = subscriptions?.get(cb);
if (!subscriptions || !subscription) return;
const membershipWillEnd = ![...subscriptions.values()].some((candidate) => candidate.callback !== cb && candidate.group === subscription.group);
if (membershipWillEnd && !this.#isBroker && this.#clientSocket && !this.#clientSocket.destroyed) {
this.#leavingSubscriptions.add(subscription);
try {
await this.#sendUnsubscribeToBroker(topic, subscription.group);
if ([...subscriptions.values()].some((candidate) => candidate.callback !== cb && candidate.group === subscription.group)) await this.#sendSubscribeToBroker(topic, subscription.group);
} catch (error) {
if (!this.#closed && !isBrokerConnectionError(error)) throw error;
} finally {
this.#leavingSubscriptions.delete(subscription);
}
}
subscriptions.delete(cb);
if (subscriptions.size === 0) this.#subscriptions.delete(topic);
if (membershipWillEnd && subscription.group !== void 0) {
this.#localGroupCursors.delete(membershipKey(topic, subscription.group));
this.#evictBrokerGroupCursor(topic, subscription.group);
}
}
async flush() {
await Promise.allSettled([...this.#pendingWrites]);
}
/** Tracks filesystem mutations so close waits for their temporary files and locks to be removed. */
#trackLeaseOperation(operation) {
this.#pendingLeaseOperations.add(operation);
operation.then(() => this.#pendingLeaseOperations.delete(operation), () => this.#pendingLeaseOperations.delete(operation));
return operation;
}
/** Rejects lease TTLs that cannot produce a finite future expiry. */
#validateLeaseTtl(ttlMs) {
if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new Error("UnixSocketPubSub lease ttlMs must be a positive finite number");
}
/**
* Creates the shared lease directories and records this process incarnation.
* The marker is rewritten whenever it has gone missing: temp-directory cleaners
* (macOS deletes `/tmp` files left unmodified for days) remove it under a
* long-lived process, and without it every process, this one included, reads
* this process's leases and mutation locks as abandoned.
*/
async #ensureLeaseDirectories() {
await this.#ensureLeaseDirectoriesOnce();
if ((await this.#readJson(join(this.#leaseProcessDirectory, `${process.pid}.json`)))?.processNonce === PROCESS_NONCE) return;
this.#leaseDirectoriesReady = void 0;
await this.#ensureLeaseDirectoriesOnce();
}
async #ensureLeaseDirectoriesOnce() {
if (!this.#leaseDirectoriesReady) this.#leaseDirectoriesReady = (async () => {
await Promise.all([
mkdir(this.#leaseDirectory, { recursive: true }),
mkdir(this.#leaseMutationDirectory, { recursive: true }),
mkdir(this.#leaseProcessDirectory, { recursive: true })
]);
const markerPath = join(this.#leaseProcessDirectory, `${process.pid}.json`);
await this.#writeJsonAtomically(markerPath, {
pid: process.pid,
processNonce: PROCESS_NONCE
});
})().catch((error) => {
this.#leaseDirectoriesReady = void 0;
throw error;
});
await this.#leaseDirectoriesReady;
}
/**
* Serializes one lease key's read-modify-write operation across processes.
* Waiting for the mutation lock stops once the pubsub closes, unless
* `finishAfterClose` is set, in which case it continues for up to
* LEASE_RELEASE_CLOSE_GRACE_MS after close.
*/
async #withLeaseMutation(key, mutate, { finishAfterClose = false } = {}) {
const throwIfAborted = () => {
if (!finishAfterClose || Date.now() - this.#closedAt > LEASE_RELEASE_CLOSE_GRACE_MS) this.#throwIfClosed();
};
await this.#ensureLeaseDirectories();
const fileName = leaseFileName(key);
const leasePath = join(this.#leaseDirectory, `${fileName}.json`);
const lockPath = join(this.#leaseMutationDirectory, `${fileName}.lock`);
const lockRecord = {
pid: process.pid,
processNonce: PROCESS_NONCE,
token: globalThis.crypto.randomUUID()
};
while (true) {
throwIfAborted();
await this.#completeLeaseMutationRecoveries(lockPath, throwIfAborted);
throwIfAborted();
const candidatePath = `${lockPath}.${process.pid}.${globalThis.crypto.randomUUID()}.tmp`;
await writeFile(candidatePath, JSON.stringify(lockRecord), { flag: "wx" });
let installed = false;
try {
await link(candidatePath, lockPath);
installed = true;
} catch (error) {
if (error.code !== "EEXIST") throw error;
const existingLock = await this.#readJson(lockPath);
if (!existingLock) {
await delay(LEASE_LOCK_RETRY_MS);
continue;
}
if (await this.#isLeaseMutationLockStale(existingLock)) await this.#startLeaseMutationRecovery(lockPath, existingLock, throwIfAborted);
else await delay(LEASE_LOCK_RETRY_MS);
} finally {
await unlink(candidatePath).catch(() => {});
}
if (!installed) continue;
let currentLock;
try {
await this.#completeLeaseMutationRecoveries(lockPath, throwIfAborted);
throwIfAborted();
currentLock = await this.#readJson(lockPath);
} catch (error) {
const heldLock = await this.#readJson(lockPath).catch(() => void 0);
if (this.#sameLeaseMutationLock(heldLock, lockRecord)) await unlink(lockPath).catch(() => {});
throw error;
}
if (this.#sameLeaseMutationLock(currentLock, lockRecord)) break;
}
try {
return await mutate(leasePath);
} finally {
await this.#releaseLeaseMutationLock(lockPath, lockRecord);
}
}
/** Returns the generation markers that block acquisition while stale-lock recovery is in progress. */
async #leaseMutationRecoveryPaths(lockPath) {
const recoveryDirectory = `${lockPath}.recoveries`;
return (await readdir(recoveryDirectory).catch(() => [])).filter((name) => name.endsWith(".marker")).map((name) => join(recoveryDirectory, name));
}
/** Completes any in-progress recovery before acquisition or release touches the canonical lock path. */
async #completeLeaseMutationRecoveries(lockPath, throwIfAborted = () => this.#throwIfClosed()) {
while (true) {
throwIfAborted();
const recoveryPaths = await this.#leaseMutationRecoveryPaths(lockPath);
if (recoveryPaths.length === 0) return;
for (const recoveryPath of recoveryPaths) await this.#completeLeaseMutationRecovery(lockPath, recoveryPath, throwIfAborted);
if ((await this.#leaseMutationRecoveryPaths(lockPath)).length > 0) await delay(LEASE_LOCK_RETRY_MS);
}
}
/** Returns a stable generation name for both current and pre-token mutation-lock records. */
async #leaseMutationLockGeneration(lock) {
if (typeof lock.token === "string") return lock.token;
const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(lock)));
return Buffer.from(digest).toString("hex");
}
#leaseMutationRecoveryOwner() {
return {
pid: process.pid,
processNonce: PROCESS_NONCE,
token: this.#leaseRecoveryOwnerToken
};
}
async #isLeaseRecoveryOwnerLive(owner) {
if (!Number.isInteger(owner.pid) || typeof owner.processNonce !== "string" || typeof owner.token !== "string") return false;
if (owner.pid === process.pid && owner.processNonce === PROCESS_NONCE) return LIVE_LEASE_RECOVERY_OWNERS.has(owner.token);
try {
process.kill(owner.pid, 0);
} catch (error) {
const code = error.code;
if (code === "ESRCH") return false;
if (code !== "EPERM") throw error;
}
return (await this.#readJson(join(this.#leaseProcessDirectory, `${owner.pid}.json`)))?.processNonce === owner.processNonce;
}
async #publishLeaseRecoveryOwner(ownerPath, owner) {
const candidatePath = `${ownerPath}.${process.pid}.${globalThis.crypto.randomUUID()}.tmp`;
try {
await writeFile(candidatePath, JSON.stringify(owner), { flag: "wx" });
await link(candidatePath, ownerPath);
return true;
} catch (error) {
const code = error.code;
if (code === "EEXIST" || code === "ENOENT") return false;
throw error;
} finally {
await unlink(candidatePath).catch(() => {});
}
}
/** Elects one immutable owner generation to finish a stale-lock recovery. */
async #ownsLeaseMutationRecovery(recoveryPath, throwIfAborted) {
const ownerDirectory = `${recoveryPath}.owners`;
const self = this.#leaseMutationRecoveryOwner();
const recoveryStillExists = async () => {
try {
await stat(recoveryPath);
return true;
} catch (error) {
if (error.code === "ENOENT") return false;
throw error;
}
};
if (!await recoveryStillExists()) return false;
await mkdir(ownerDirectory, { recursive: true });
while (true) {
throwIfAborted();
if (!await recoveryStillExists()) {
await rm(ownerDirectory, {
recursive: true,
force: true
});
return false;
}
let ownerNames;
try {
ownerNames = (await readdir(ownerDirectory)).filter((name) => /^\d+\.json$/.test(name)).sort((first, second) => Number(first.slice(0, -5)) - Number(second.slice(0, -5)));
} catch (error) {
if (error.code === "ENOENT") return false;
throw error;
}
const latestName = ownerNames.at(-1);
if (latestName) {
const latestOwner = await this.#readJson(join(ownerDirectory, latestName));
if (latestOwner && await this.#isLeaseRecoveryOwnerLive(latestOwner)) return latestOwner.token === self.token && latestOwner.processNonce === self.processNonce && latestOwner.pid === self.pid;
}
if (!await recoveryStillExists()) {
await rm(ownerDirectory, {
recursive: true,
force: true
});
return false;
}
const nextGeneration = latestName ? Number(latestName.slice(0, -5)) + 1 : 0;
if (await this.#publishLeaseRecoveryOwner(join(ownerDirectory, `${nextGeneration}.json`), self)) return true;
}
}
/** Creates the immutable recovery marker before electing the generation's recovery owner. */
async #startLeaseMutationRecovery(lockPath, expected, throwIfAborted) {
const recoveryDirectory = `${lockPath}.recoveries`;
const recoveryPath = join(recoveryDirectory, `${await this.#leaseMutationLockGeneration(expected)}.marker`);
await mkdir(recoveryDirectory, { recursive: true });
const current = await this.#readJson(lockPath);
if (!this.#sameLeaseMutationLock(current, expected)) return;
try {
await link(lockPath, recoveryPath);
} catch (error) {
const code = error.code;
if (code === "ENOENT") return;
if (code !== "EEXIST") throw error;
}
await this.#completeLeaseMutationRecovery(lockPath, recoveryPath, throwIfAborted);
}
/** Removes one stale generation; every other contender waits while its marker remains. */
async #completeLeaseMutationRecovery(lockPath, recoveryPath, throwIfAborted) {
if (!await this.#ownsLeaseMutationRecovery(recoveryPath, throwIfAborted)) return;
const expectedGeneration = basename(recoveryPath, ".marker");
const expected = await this.#readJson(recoveryPath);
if (!expected || await this.#leaseMutationLockGeneration(expected) !== expectedGeneration || !await this.#isLeaseMutationLockStale(expected)) {
await this.#removeLeaseMutationRecovery(recoveryPath);
return;
}
const current = await this.#readJson(lockPath);
if (!this.#sameLeaseMutationLock(current, expected)) {
await this.#removeLeaseMutationRecovery(recoveryPath);
return;
}
const isolatedPath = `${recoveryPath}.${this.#leaseRecoveryOwnerToken}.isolated`;
try {
await rename(lockPath, isolatedPath);
} catch (error) {
if (error.code !== "ENOENT") throw error;
}
const isolated = await this.#readJson(isolatedPath);
if (isolated && !this.#sameLeaseMutationLock(isolated, expected)) {
await link(isolatedPath, lockPath).catch((error) => {
if (error.code !== "EEXIST") throw error;
});
throw new Error("UnixSocketPubSub lease recovery isolated an unexpected mutation lock");
}
await unlink(isolatedPath).catch(() => {});
await this.#removeLeaseMutationRecovery(recoveryPath);
}
async #removeLeaseMutationRecovery(recoveryPath) {
await unlink(recoveryPath).catch(() => {});
await rm(`${recoveryPath}.owners`, {
recursive: true,
force: true
});
}
/** Releases this holder's immutable lock generation after any earlier recovery has completed. */
async #releaseLeaseMutationLock(lockPath, expected) {
if (!this.#closed) await this.#completeLeaseMutationRecoveries(lockPath);
const current = await this.#readJson(lockPath);
if (this.#sameLeaseMutationLock(current, expected)) await unlink(lockPath).catch(() => {});
}
/** Compares mutation-lock identities without relying on a reusable pathname. */
#sameLeaseMutationLock(first, second) {
return first !== void 0 && second !== void 0 && first.pid === second.pid && first.processNonce === second.processNonce && first.token === second.token;
}
/** Detects abandoned mutation locks using both PID liveness and process incarnation. */
async #isLeaseMutationLockStale(lock) {
if (!Number.isInteger(lock.pid) || typeof lock.processNonce !== "string") return true;
try {
process.kill(lock.pid, 0);
} catch (error) {
const code = error.code;
if (code === "ESRCH") return true;
if (code !== "EPERM") throw error;
}
return (await this.#readJson(join(this.#leaseProcessDirectory, `${lock.pid}.json`)))?.processNonce !== lock.processNonce;
}
/** Reads and validates a persisted lease record. */
async #readLease(leasePath) {
const record = await this.#readJson(leasePath);
if (!record || typeof record.owner !== "string" || !Number.isFinite(record.expiresAt) || !Number.isInteger(record.pid) || typeof record.processNonce !== "string") return;
return record;
}
/** Verifies that a lease is unexpired and still belongs to the recorded process incarnation. */
async #isLeaseRecordLive(record) {
if (record.expiresAt <= Date.now()) return false;
try {
process.kill(record.pid, 0);
} catch (error) {
const code = error.code;
if (code === "ESRCH") return false;
if (code !== "EPERM") throw error;
}
return (await this.#readJson(join(this.#leaseProcessDirectory, `${record.pid}.json`)))?.processNonce === record.processNonce;
}
/** Persists a lease for this process incarnation with a refreshed expiry. */
async #writeLease(leasePath, owner, ttlMs) {
await this.#writeJsonAtomically(leasePath, {
owner,
expiresAt: Date.now() + ttlMs,
pid: process.pid,
processNonce: PROCESS_NONCE
});
}
/** Reads JSON while treating missing or partially written files as absent. */
async #readJson(path) {
try {
return JSON.parse(await readFile(path, "utf8"));
} catch (error) {
if (error.code === "ENOENT" || error instanceof SyntaxError) return void 0;
throw error;
}
}
/** Replaces a JSON file atomically so readers never observe partial contents. */
async #writeJsonAtomically(path, value) {
const tempPath = `${path}.${process.pid}.${globalThis.crypto.randomUUID()}.tmp`;
await writeFile(tempPath, JSON.stringify(value), { flag: "wx" });
try {
await rename(tempPath, path);
} finally {
await unlink(tempPath).catch(() => {});
}
}
#hasLocalMembership(topic, group) {
return [...this.#subscriptions.get(topic)?.values() ?? []].some((subscription) => subscription.group === group);
}
#localGroups(topic) {
return [...new Set([...this.#subscriptions.get(topic)?.values() ?? []].map((subscription) => subscription.group).filter((group) => group !== void 0))];
}
async close() {
if (!this.#closed) this.#closedAt = Date.now();
this.#closed = true;
this.#subscriptions.clear();
this.#localGroupCursors.clear();
this.#brokerGroupCursors.clear();
this.#clientSocket?.destroy();
this.#clientSocket = void 0;
this.#rejectMembershipWaiters(/* @__PURE__ */ new Error("UnixSocketPubSub is closed"));
this.#stopBrokerPathCheck();
if (this.#isBroker) await this.#removeSocketPathIf(this.#serverIdentity);
const clientClosures = [...this.#brokerClients.values()].map((client) => new Promise((resolve) => {
if (client.socket.destroyed) {
this.#removeBrokerClient(client);
resolve();
return;
}
client.socket.once("close", resolve);
this.#removeBrokerClient(client);
}));
await Promise.allSettled(clientClosures);
if (this.#server) {
await closeServer(this.#server);
this.#server = void 0;
}
this.#serverIdentity = void 0;
await Promise.allSettled([...this.#pendingLeaseOperations]);
LIVE_LEASE_RECOVERY_OWNERS.delete(this.#leaseRecoveryOwnerToken);
this.#isBroker = false;
}
/** Removes socketPath only if it still has `identity`, so nobody deletes a socket file they did not prove is theirs or dead. */
async #removeSocketPathIf(identity) {
if (sameIdentity(await fileIdentity(this.socketPath).catch(() => void 0), identity)) await unlink(this.socketPath).catch(() => {});
}
async #ensureStarted(forceReconnect = false) {
if (this.#closed) throw new Error("UnixSocketPubSub is closed");
if (this.#isBroker || !forceReconnect && this.#clientSocket && !this.#clientSocket.destroyed) return;
if (this.#starting) return this.#starting;
this.#starting = this.#start(forceReconnect).finally(() => {
this.#starting = void 0;
});
return this.#starting;
}
async #start(forceReconnect) {
if (forceReconnect) {
this.#clientSocket?.destroy();
this.#clientSocket = void 0;
this.#isBroker = false;
}
this.#throwIfClosed();
await mkdir(dirname(this.socketPath), { recursive: true });
let retries = 0;
for (;;) {
this.#throwIfClosed();
let code;
try {
await this.#connectClient();
this.#throwIfClosed();
return;
} catch (error) {
if (this.#closed) {
await this.close();
throw new Error("UnixSocketPubSub is closed");
}
code = error.code;
if (code === "EAGAIN" || isBrokerConnectionError(error)) {
if (retries >= CONNECT_RETRY_DELAYS_MS.length) throw error;
await delay(CONNECT_RETRY_DELAYS_MS[retries++]);
continue;
}
if (code !== "ENOENT" && code !== "ECONNREFUSED" && code !== "ENOTSOCK") throw error;
}
if (code === "ENOENT") {
if (await this.#bindIfAbsent()) return;
continue;
}
if (retries < CONNECT_RETRY_DELAYS_MS.length && code !== "ENOTSOCK") {
await delay(CONNECT_RETRY_DELAYS_MS[retries++]);
continue;
}
await this.#electBroker();
return;
}
}
#throwIfClosed() {
if (this.#closed) throw new Error("UnixSocketPubSub is closed");
}
/**
* Becomes the broker only if nothing is at socketPath. The socket is bound
* at a private name and hard-linked into place: link() fails with EEXIST
* rather than replacing, so this never takes over another broker's path.
* The private name also matters on close, because libuv unlinks a pipe
* server's bound path by name, which would otherwise delete whichever
* broker's file is at socketPath by then.
*/
async #bindIfAbsent() {
const { server, privatePath } = await this.#listenAtPrivatePath();
let published = false;
try {
const identity = await fileIdentity(privatePath);
try {
await link(privatePath, this.socketPath);
published = true;
} catch (error) {
if (error.code === "EEXIST") return false;
throw error;
}
this.#server = server;
this.#serverIdentity = identity;
this.#isBroker = true;
this.#startBrokerPathCheck();
} finally {
await unlink(privatePath).catch(() => {});
if (!published) await closeServer(server);
}
if (this.#closed) {
await this.close();
throw new Error("UnixSocketPubSub is closed");
}
return true;
}
/**
* The socket path limit applies to the whole path, so the private name is
* shortened when the directory leaves less than 13 bytes, but never below
* the shared basename: wherever the shared path binds, the private path
* does too. Short names can collide with another candidate or a leftover
* file, so a taken name is retried.
*/
async #listenAtPrivatePath() {
const sharedName = basename(this.socketPath);
const sharedNameLength = Buffer.byteLength(sharedName);
const room = MAX_SOCKET_PATH_BYTES - (Buffer.byteLength(this.socketPath) - sharedNameLength);
const nameLength = Math.min(13, Math.max(sharedNameLength, room));
for (let attempt = 1;; attempt++) {
const hex = Buffer.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(6))).toString("hex");
const name = nameLength > 1 ? `.${hex.slice(0, nameLength - 1)}` : hex.slice(0, 1);
if (name === sharedName) continue;
const joined = join(dirname(this.socketPath), name);
const privatePath = joined.includes(sep) ? joined : `.${sep}${joined}`;
try {
return {
server: await this.#listen(privatePath),
privatePath
};
} catch (error) {
if (error.code !== "EADDRINUSE" || attempt >= 5) throw error;
}
}
}
#listen(path) {
return new Promise((resolve, reject) => {
const server = net.createServer((socket) => this.#handleBrokerClient(socket));
const onError = (error) => {
server.off("listening", onListening);
reject(error);
};
const onListening = () => {
server.off("error", onError);
resolve(server);
};
server.once("error", onError);
server.once("listening", onListening);
server.listen(path);
});
}
#startBrokerPathCheck() {
this.#stopBrokerPathCheck();
this.#brokerPathCheckTimer = setInterval(() => void this.#checkBrokerPath(), this.#brokerPathCheckIntervalMs);
this.#brokerPathCheckTimer.unref?.();
}
#stopBrokerPathCheck() {
if (this.#brokerPathCheckTimer) clearInterval(this.#brokerPathCheckTimer);
this.#brokerPathCheckTimer = void 0;
}
/**
* Hands over if socketPath no longer leads to this broker. A broker whose
* file was deleted or replaced still serves its connected clients, but no
* new instance can reach it, so they form a separate group that never
* hears the others' events.
*/
async #checkBrokerPath() {
if (!this.#isBroker || this.#closed || this.#relinquishing) return;
const identity = this.#serverIdentity;
let current;
try {
current = await fileIdentity(this.socketPath);
} catch {
return;
}
if (!this.#isBroker || this.#closed || this.#serverIdentity !== identity || sameIdentity(current, identity)) return;
this.#relinquishing = this.#relinquishBroker().finally(() => {
this.#relinquishing = void 0;
});
await this.#relinquishing;
}
/** Stops serving and rejoins through normal election; dropped clients do the same. */
async #relinquishBroker() {
const server = this.#server;
this.#stopBrokerPathCheck();
this.#isBroker = false;
this.#server = void 0;
this.#serverIdentity = void 0;
this.#brokerGroupCursors.clear();
for (const client of [...this.#brokerClients.values()]) this.#removeBrokerClient(client);
if (server) await closeServer(server);
if (!this.#closed) await this.#recoverClientConnection();
}
#connectClient() {
return new Promise((resolve, reject) => {
const socket = net.createConnection(this.socketPath);
const onError = (error) => {
socket.off("connect", onConnect);
reject(error);
};
const onConnect = () => {
socket.off("error", onError);
this.#clientSocket = socket;
this.#isBroker = false;
readFrames(socket, (frame) => this.#handleServerFrame(socket, frame), this.#maxInboundFrameBytes);
socket.on("close", () => this.#handleClientDisconnect(socket, /* @__PURE__ */ new Error("UnixSocketPubSub broker connection closed")));
socket.on("error", (error) => this.#handleClientDisconnect(socket, error));
this.#resubscribeClient(socket).then(resolve, reject);
};
socket.once("error", onError);
socket.once("connect", onConnect);
});
}
/**
* Re-registers memberships on a connection that `#start` is still setting
* up. Frames go straight to `socket`: the usual reconnect-and-retry path
* would wait on the in-flight start, which is waiting on this, and hang
* forever if the broker drops the connection mid-resubscribe.
*/
async #resubscribeClient(socket) {
for (const [topic, subscriptions] of this.#subscriptions) {
const groups = new Set([...subscriptions.values()].filter((subscription) => !this.#leavingSubscriptions.has(subscription)).map((subscription) => subscription.group));
for (const group of groups) await this.#sendMembershipFrameToBroker({
type: "subscribe",
topic,
group
}, this.#subscribeWaiters, socket);
}
}
#handleClientDisconnect(socket, error) {
if (this.#clientSocket !== socket) return;
this.#clientSocket = void 0;
this.#rejectMembershipWaiters(error);
if (!this.#closed) this.#recoverClientConnection();
}
async #recoverClientConnection() {
if (this.#recovering) return this.#recovering;
this.#recovering = this.#recoverClientConnectionLoop().finally(() => {
this.#recovering = void 0;
});
return this.#recovering;
}
async #recoverClientConnectionLoop() {
while (!this.#closed && !this.#isBroker && !(this.#clientSocket && !this.#clientSocket.destroyed)) try {
await this.#ensureStarted(true);
return;
} catch {
if (this.#closed) return;
await new Promise((resolve) => setTimeout(resolve, 10));
}
}
/**
* Serializes broker election across processes using an exclusive lock file.
* This is the only place a socket file is removed by anyone but its own
* broker: the lock winner removes it only after a connect under the lock is
* refused and the file is still the one it probed. Losers wait, then
* connect as clients to the newly elected broker.
*/
async #electBroker() {
const lockPath = this.socketPath + ".elect";
let lockFd;
try {
lockFd = await open(lockPath, "wx");
} catch (e) {
if (e.code === "EEXIST") {
if (await this.#isElectionLockStale(lockPath)) {
await unlink(lockPath).catch(() => {});
throw new Error("Stale broker election lock removed");
}
await new Promise((resolve) => setTimeout(resolve, 150));
try {
await this.#connectClient();
this.#throwIfClosed();
return;
} catch {
throw new Error("Broker election in progress by another process");
}
}
throw e;
}
const lockIdentity = await lockFd.stat().then(({ dev, ino }) => ({
dev,
ino
})).catch(() => void 0);
try {
const probed = await fileIdentity(this.socketPath);
try {
await this.#connectClient();
this.#throwIfClosed();
return;
} catch (error) {
this.#throwIfClosed();
const code = error.code;
if (code !== "ECONNREFUSED" && code !== "ENOENT" && code !== "ENOTSOCK") throw error;
}
if (probed) await this.#removeSocketPathIf(probed);
if (await this.#bindIfAbsent()) return;
await this.#connectClient();
this.#throwIfClosed();
} finally {
await lockFd.close().catch(() => {});
if (sameIdentity(await fileIdentity(lockPath).catch(() => void 0), lockIdentity)) await unlink(lockPath).catch(() => {});
}
}
async #isElectionLockStale(lockPath) {
try {
const lockStat = await stat(lockPath);
return Date.now() - lockStat.mtimeMs > 2e3;
} catch {
return true;
}
}
async #sendSubscribeToBroker(topic, group) {
await this.#sendMembershipFrameToBroker({
type: "subscribe",
topic,
group
}, this.#subscribeWaiters);
}
async #sendUnsubscribeToBroker(topic, group) {
await this.#sendMembershipFrameToBroker({
type: "unsubscribe",
topic,
group
}, this.#unsubscribeWaiters);
}
async #sendMembershipFrameToBroker(frame, waiterMap, socket) {
const key = membershipKey(frame.topic, frame.group);
let waiter;
let acknowledged;
const registerWaiter = () => {
if (waiter) {
const waiters = waiterMap.get(key);
const index = waiters?.indexOf(waiter) ?? -1;
if (index !== -1) waiters.splice(index, 1);
if (waiters?.length === 0) waiterMap.delete(key);
}
acknowledged = new Promise((resolve, reject) => {
waiter = {
resolve,
reject
};
const waiters = waiterMap.get(key) ?? [];
waiters.push(waiter);
waiterMap.set(key, waiters);
});
acknowledged.catch(() => {});
};
try {
if (socket) {
registerWaiter();
await this.#writePublisherFrame(socket, frame);
} else await this.#sendToBroker(frame, registerWaiter);
} catch (error) {
this.#settleMembershipWaiters(waiterMap, key, error instanceof Error ? error : new Error(String(error)));
}
const ackTimeout = setTimeout(() => {
this.#settleMembershipWaiters(waiterMap, key);
}, this.#membershipAckTimeoutMs);
ackTimeout.unref?.();
try {
await acknowledged;
} finally {
clearTimeout(ackTimeout);
}
}
#waitForPendingMembershipAcknowledgement(waiterMap, key) {
const waiters = waiterMap.get(key);
if (!waiters) return Promise.resolve();
return new Promise((resolve, reject) => {
waiters.push({
resolve,
reject
});
});
}
#settleMembershipWaiters(waiterMap, key, error) {
const waiters = waiterMap.get(key);
waiterMap.delete(key);
if (error) {
waiters?.forEach((waiter) => waiter.reject(error));
return;
}
waiters?.forEach((waiter) => waiter.resolve());
}
#rejectMembershipWaiters(error) {
for (const waiterMap of [this.#subscribeWaiters, this.#unsubscribeWaiters]) for (const key of waiterMap.keys()) this.#settleMembershipWaiters(waiterMap, key, error);
}
#handleBrokerClient(socket) {
if (this.#closed) {
socket.destroy();
return;
}
const client = {
socket,
subscriptions: /* @__PURE__ */ new Set(),
writeChain: Promise.resolve(),
queuedBytes: 0
};
this.#brokerClients.set(socket, client);
readFrames(socket, (frame) => {
const clientFrame = frame;
if (clientFrame.type === "subscribe") {
client.subscriptions.add(membershipKey(clientFrame.topic, clientFrame.group));
this.#enqueueBrokerClientWrite(client, {
type: "subscribed",
topic: clientFrame.topic,
...clientFrame.group !== void 0 ? { group: clientFrame.group } : {}
});
} else if (clientFrame.type === "unsubscribe") {
client.subscriptions.delete(membershipKey(clientFrame.topic, clientFrame.group));
if (clientFrame.group !== void 0) this.#evictBrokerGroupCursor(clientFrame.topic, clientFrame.group);
this.#enqueueBrokerClientWrite(client, {
type: "unsubscribed",
topic: clientFrame.topic,
...clientFrame.group !== void 0 ? { group: clientFrame.group } : {}
});
} else if (clientFrame.type === "publish") this.#publishFromBroker(clientFrame.topic, clientFrame.event, client, clientFrame.localOnly);
}, this.#maxInboundFrameBytes);
socket.on("close", () => this.#removeBrokerClient(client));
socket.on("error", () => this.#removeBrokerClient(client));
}
#enqueueBrokerClientWrite(client, frame) {
if (this.#brokerClients.get(client.socket) !== client || client.socket.destroyed) return;
const serializedFrame = serializeFrame(frame);
const queuedBytes = Buffer.byteLength(serializedFrame);
if (client.queuedBytes + queuedBytes > this.#maxRemoteClientQueuedBytes) {
this.#removeBrokerClient(client);
return;
}
client.queuedBytes += queuedBytes;
const write = client.writeChain.catch(() => {}).then(async () => {
if (this.#brokerClients.get(client.socket) !== client || client.socket.destroyed) return;
await writeSerializedFrame(client.socket, serializedFrame);
}).catch(() => {
this.#removeBrokerClient(client);
}).finally(() => {
client.queuedBytes = Math.max(0, client.queuedBytes - queuedBytes);
});
client.writeChain = write;
this.#pendingWrites.add(write);
write.finally(() => this.#pendingWrites.delete(write));
}
#evictBrokerGroupCursor(topic, group) {
const key = membershipKey(topic, group);
if (this.#hasLocalMembership(topic, group)) return;
if ([...this.#brokerClients.values()].some((client) => client.subscriptions.has(key))) return;
this.#brokerGroupCursors.delete(key);
}
#removeBrokerClient(client) {
if (this.#brokerClients.get(client.socket) !== client) return;
const subscriptions = [...client.subscriptions];
this.#brokerClients.delete(client.socket);
client.subscriptions.clear();
for (const subscription of subscriptions) {
const [topic, group] = JSON.parse(subscription);
if (group !== null) this.#evictBrokerGroupCursor(topic, group);
}
client.queuedBytes = 0;
client.writeChain = Promise.resolve();
if (!client.socket.destroyed) client.socket.destroy();
}
#handleServerFrame(socket, frame) {
if ((frame.type === "subscribed" || frame.type === "unsubscribed") && socket !== this.#clientSocket) return;
if (frame.type === "subscribed") {
this.#settleMembershipWaiters(this.#subscribeWaiters, membershipKey(frame.topic, frame.group));
return;
}
if (frame.type === "unsubscribed") {
this.#settleMembershipWaiters(this.#unsubscribeWaiters, membershipKey(frame.topic, frame.group));
return;
}
if (frame.type !== "event") return;
if (frame.group !== void 0) this.#deliverLocalGroup(frame.topic, frame.group, frame.event);
else this.#deliverLocalFanout(frame.topic, frame.event);
}
async #publishFromBroker(topic, event, sourceClient, localOnly) {
const brokerEvent = {
...event,
id: globalThis.crypto.randomUUID(),
createdAt: /* @__PURE__ */ new Date(),
deliveryAttempt: 1
};
this.#deliverLocalFanout(topic, brokerEvent);
if (localOnly) {
if (sourceClient && sourceClient.subscriptions.has(membershipKey(topic)) && !sourceClient.socket.destroyed) this.#enqueueBrokerClientWrite(sourceClient, {
type: "event",
topic,
event: brokerEvent
});
return;
}
const fanoutFrame = {
type: "event",
topic,
event: brokerEvent
};
for (const client of this.#brokerClients.values()) {
if (!client.subscriptions.has(membershipKey(topic)) || client.socket.destroyed) continue;
this.#enqueueBrokerClientWrite(client, fanoutFrame);
}
const groups = new Set(this.#localGroups(topic));
for (const client of this.#brokerClients.values()) for (const subscription of client.subscriptions) {
const [subscriptionTopic, group] = JSON.parse(subscription);
if (subscriptionTopic === topic && group !== null) groups.add(group);
}
for (const group of groups) {
const members = [];
if (this.#hasLocalMembership(topic, group)) members.push("local");
for (const client of this.#brokerClients.values()) if (client.subscriptions.has(membershipKey(topic, group)) && !client.socket.destroyed) members.push(client);
if (members.length === 0) continue;
const key = membershipKey(topic, group);
const cursor = this.#brokerGroupCursors.get(key) ?? 0;
const member = members[cursor % members.length];
this.#brokerGroupCursors.set(key, (cursor + 1) % members.length);
if (member === "local") this.#deliverLocalGroup(topic, group, brokerEvent);
else this.#enqueueBrokerClientWrite(member, {
type: "event",
topic,
event: brokerEvent,
group
});
}
}
#deliverLocal(topic, event) {
this.#deliverLocalFanout(topic, event);
for (const group of this.#localGroups(topic)) this.#deliverLocalGroup(topic, group, event);
}
#deliverLocalFanout(topic, event) {
for (const subscription of this.#subscriptions.get(topic)?.values() ?? []) {
if (subscription.group !== void 0) continue;
this.#invokeLocalCallback(topic, event, subscription.callback, subscription.group, 0);
}
}
#deliverLocalGroup(topic, group, event) {
const members = [...this.#subscriptions.get(topic)?.values() ?? []].filter((subscription) => subscription.group === group);
if (members.length === 0) return;
const key = membershipKey(topic, group);
const cursor = this.#localGroupCursors.get(key) ?? 0;
const member = members[cursor % members.length];
this.#localGroupCursors.set(key, (cursor + 1) % members.length);
this.#invokeLocalCallback(topic, event, member.callback, group, 0);
}
#invokeLocalCallback(topic, event, cb, group, attempt) {
let nacked = false;
const nack = async () => {
if (nacked || this.#closed) return;
nacked = true;
if (attempt >= 6) return;
const currentSubscription = this.#subscriptions.get(topic)?.get(cb);
if (!currentSubscription || currentSubscription.group !== group) return;
setTimeout(() => {
if (this.#closed) return;
const currentSubscription = this.#subscriptions.get(topic)?.get(cb);
if (!currentSubscription || currentSubscription.group !== group) return;
const redeliveredEvent = {
...event,
deliveryAttempt: (event.deliveryAttempt ?? 1) + 1
};
this.#invokeLocalCallback(topic, redeliveredEvent, cb, group, attempt + 1);
}, REDELIVERY_DELAY_MS * (attempt + 1)).unref?.();
};
try {
const result = cb(event, async () => {}, nack);
if (result && typeof result.catch === "function") result.catch(() => {});
} catch {}
}
async #sendToBroker(frame, beforeAttempt) {
const maxRetries = 3;
let lastError;
for (let attempt = 0; attempt <= maxRetries; attempt++) try {
if (attempt === 0) {
beforeAttempt?.();
await this.#sendToActiveBroker(frame);
} else {
if (this.#closed) throw closedError(lastError);
const failedSocket = this.#clientSocket;
this.#clientSocket = void 0;
failedSocket?.destroy();
beforeAttempt?.();
await this.#ensureStarted(true);
await this.#sendToActiveBroker(frame);
}
return;
} catch (error) {
lastError = error;
if (this.#closed) {
if (error instanceof Error && error.message === "UnixSocketPubSub is closed") throw error;
throw closedError(error);
}
if (!isBrokerConnectionError(error) || attempt === maxRetries) throw error;
await new Promise((resolve) => setTimeout(resolve, 10 * (attempt + 1)));
}
}
async #sendToActiveBroker(frame) {
const socket = this.#clientSocket;
if (!socket || socket.destroyed) await this.#ensureStarted(true);
if (this.#isBroker) {
await this.#handlePromotedBrokerFrame(frame);
return;
}
const activeSocket = this.#clientSocket;
if (!activeSocket || activeSocket.destroyed) throw new Error("UnixSocketPubSub is not connected to a broker");
await this.#writePublisherFrame(activeSocket, frame);
}
async #writePublisherFrame(socket, frame) {
const serialized = serializeFrame(frame);
const bytes = Buffer.byteLength(serialized);
if (this.#publisherQueuedBytes + bytes > this.#maxPublisherQueuedBytes) {
const waitForCapacity = bytes <= this.#maxPublisherQueuedBytes ? () => this.#publisherQueuedBytes + bytes <= this.#maxPublisherQueuedBytes ? Promise.resolve() : new Promise((resolve) => this.#publisherCapacityWaiters.add(resolve)) : void 0;
throw new PublisherQueueLimitError("UnixSocketPubSub publisher queue limit exceeded", waitForCapacity);
}
this.#publisherQueuedBytes += bytes;
try {
await writeSerializedFrame(socket, serialized);
} finally {
this.#publisherQueuedBytes -= bytes;
for (const resolve of this.#publisherCapacityWaiters) resolve();
this.#publisherCapacityWaiters.clear();
}
}
async #handlePromotedBrokerFrame(frame) {
if (frame.type === "subscribe") this.#settleMembershipWaiters(this.#subscribeWaiters, membershipKey(frame.topic, frame.group));
else if (frame.type === "unsubscribe") this.#settleMembershipWaiters(this.#unsubscribeWaiters, membershipKey(frame.topic, frame.group));
else if (frame.type === "publish") await this.#publishFromBroker(frame.topic, frame.event);
}
};
export { CachingPubSub, EventEmitterPubSub, MAX_LOCAL_REDELIVERIES, NoopLeaseProvider, PubSub, RUN_LOCAL_TOPIC_PREFIXES, RUN_LOG_TTL_MS, UnixSocketPubSub, cachedLogTtlMs, isLeaseProvider, isRunLocalTopic, toCachedLogFrame, withAck, withCaching };
//# sourceMappingURL=index.js.map
Shown as plain text from the published tarball, after apm checked it against the version's checksum. Nothing in it runs on this page.