@ubercode/dcmtk 0.15.0 → 0.16.0

package/dist/{index-D7nnTY1R.d.ts → index-C6dWOhHS.d.ts}

@@ -1567,6 +1567,14 @@ interface ReceiverAssociationFinalizedData {
     readonly files: readonly string[];
     readonly instancesReceived: number;
     readonly instanceErrors: number;
+    /**
+     * How the association ended: `'release'` for a normal A-RELEASE, `'abort'`
+     * for a peer abort (including associations synthesized by the grace-period
+     * reaper when dcmrecv never reported completion). Lets consumers that drive
+     * terminal state off this event distinguish a reaped abort from a clean
+     * finish without also listening to ASSOCIATION_COMPLETE.
+     */
+    readonly endReason: 'release' | 'abort';
 }
 /** Data emitted with error events. */
 interface ReceiverErrorData {
@@ -1787,6 +1795,17 @@ declare class DicomReceiver extends EventEmitter<DicomReceiverEventMap> {
     private getIdleWorker;
     /** Pipes remote socket bidirectionally to the worker's port. */
     private pipeConnection;
+    /**
+     * After a connection's sockets tear down, reaps the association as an
+     * aborted one *only if* dcmrecv never reported completion within
+     * {@link ABORT_REAP_GRACE_MS}. Without this, a peer abort destroys the
+     * sockets but dcmrecv may never emit ASSOCIATION_COMPLETE, so the worker
+     * stays busy forever, ASSOCIATION_FINALIZED never fires (consumers can't
+     * release per-association state), and the association directory is never
+     * removed. The grace delay ensures a normal A-RELEASE — whose socket also
+     * closes — is finalized by its own completion report and never reaped here.
+     */
+    private scheduleAbortReap;
     /** Spawns `count` new workers and adds them to the pool. */
     private spawnWorkers;
     /** Creates a Dcmrecv instance with the pool's shared options. */
@@ -1811,7 +1830,19 @@ declare class DicomReceiver extends EventEmitter<DicomReceiverEventMap> {
     private parseAndEmitInstance;
     /** Returns worker to idle pool on association complete, emits summary. */
     private wireAssociationComplete;
-    /** Awaits file ops, emits ASSOCIATION_COMPLETE, awaits parsing, emits ASSOCIATION_FINALIZED. */
+    /**
+     * Awaits file ops, emits ASSOCIATION_COMPLETE, awaits parsing, emits
+     * ASSOCIATION_FINALIZED, returns the worker to idle. Runs at most once per
+     * association via {@link Worker.beginFinalizeOnce}.
+     *
+     * @param removeDir - When true, removes the association directory after
+     *   finalizing. Set when no consumer ever engaged with the association
+     *   (no ASSOCIATION_RECEIVED was emitted) — e.g. a connection that aborted
+     *   during negotiation — so the pool reclaims the directory it created.
+     *   When a consumer did engage this stays false: the consumer owns
+     *   directory cleanup once it has processed the received files (removing it
+     *   here could race in-flight consumer reads of those files).
+     */
     private finalizeAssociation;
     /** Emits the ASSOCIATION_COMPLETE event with transfer stats. */
     private emitAssociationComplete;

package/dist/{index-CtqMUrjP.d.cts → index-D1msvaAt.d.cts}

@@ -1567,6 +1567,14 @@ interface ReceiverAssociationFinalizedData {
     readonly files: readonly string[];
     readonly instancesReceived: number;
     readonly instanceErrors: number;
+    /**
+     * How the association ended: `'release'` for a normal A-RELEASE, `'abort'`
+     * for a peer abort (including associations synthesized by the grace-period
+     * reaper when dcmrecv never reported completion). Lets consumers that drive
+     * terminal state off this event distinguish a reaped abort from a clean
+     * finish without also listening to ASSOCIATION_COMPLETE.
+     */
+    readonly endReason: 'release' | 'abort';
 }
 /** Data emitted with error events. */
 interface ReceiverErrorData {
@@ -1787,6 +1795,17 @@ declare class DicomReceiver extends EventEmitter<DicomReceiverEventMap> {
     private getIdleWorker;
     /** Pipes remote socket bidirectionally to the worker's port. */
     private pipeConnection;
+    /**
+     * After a connection's sockets tear down, reaps the association as an
+     * aborted one *only if* dcmrecv never reported completion within
+     * {@link ABORT_REAP_GRACE_MS}. Without this, a peer abort destroys the
+     * sockets but dcmrecv may never emit ASSOCIATION_COMPLETE, so the worker
+     * stays busy forever, ASSOCIATION_FINALIZED never fires (consumers can't
+     * release per-association state), and the association directory is never
+     * removed. The grace delay ensures a normal A-RELEASE — whose socket also
+     * closes — is finalized by its own completion report and never reaped here.
+     */
+    private scheduleAbortReap;
     /** Spawns `count` new workers and adds them to the pool. */
     private spawnWorkers;
     /** Creates a Dcmrecv instance with the pool's shared options. */
@@ -1811,7 +1830,19 @@ declare class DicomReceiver extends EventEmitter<DicomReceiverEventMap> {
     private parseAndEmitInstance;
     /** Returns worker to idle pool on association complete, emits summary. */
     private wireAssociationComplete;
-    /** Awaits file ops, emits ASSOCIATION_COMPLETE, awaits parsing, emits ASSOCIATION_FINALIZED. */
+    /**
+     * Awaits file ops, emits ASSOCIATION_COMPLETE, awaits parsing, emits
+     * ASSOCIATION_FINALIZED, returns the worker to idle. Runs at most once per
+     * association via {@link Worker.beginFinalizeOnce}.
+     *
+     * @param removeDir - When true, removes the association directory after
+     *   finalizing. Set when no consumer ever engaged with the association
+     *   (no ASSOCIATION_RECEIVED was emitted) — e.g. a connection that aborted
+     *   during negotiation — so the pool reclaims the directory it created.
+     *   When a consumer did engage this stays false: the consumer owns
+     *   directory cleanup once it has processed the received files (removing it
+     *   here could race in-flight consumer reads of those files).
+     */
     private finalizeAssociation;
     /** Emits the ASSOCIATION_COMPLETE event with transfer stats. */
     private emitAssociationComplete;

package/dist/index.cjs

@@ -31290,8 +31290,14 @@ var KNOWN_VR_CODES = /* @__PURE__ */ new Set([
   "UT",
   "UV"
 ]);
+function decodeXmlEntities(value) {
+  return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function decodeIfString(value) {
+  return typeof value === "string" ? decodeXmlEntities(value) : value;
+}
 function buildPnString(comp) {
-  const parts = [comp.FamilyName ?? "", comp.GivenName ?? "", comp.MiddleName ?? "", comp.NamePrefix ?? "", comp.NameSuffix ?? ""];
+  const parts = [comp.FamilyName ?? "", comp.GivenName ?? "", comp.MiddleName ?? "", comp.NamePrefix ?? "", comp.NameSuffix ?? ""].map(decodeXmlEntities);
   let last = parts.length - 1;
   for (; last >= 0; last--) {
     if (parts[last] !== "") break;
@@ -31330,9 +31336,9 @@ function convertBulkDataURI(attr, element) {
   const bulkArray = toArray(attr.BulkDataURI);
   const firstBulk = bulkArray[0];
   if (typeof firstBulk === "object" && firstBulk !== null && "@_uri" in firstBulk) {
-    element.BulkDataURI = safeString(firstBulk["@_uri"]);
+    element.BulkDataURI = decodeXmlEntities(safeString(firstBulk["@_uri"]));
   } else {
-    element.BulkDataURI = safeString(firstBulk);
+    element.BulkDataURI = decodeXmlEntities(safeString(firstBulk));
   }
 }
 function convertPNValue(attr, element) {
@@ -31376,7 +31382,7 @@ function convertRegularValue(attr, element, vr) {
   const values = [];
   const isNumeric = NUMERIC_JSON_VRS.has(vr);
   for (const v of valArray) {
-    const unwrapped = unwrapValue(v);
+    const unwrapped = decodeIfString(unwrapValue(v));
     values.push(isNumeric ? coerceNumeric(unwrapped) : unwrapped);
   }
   if (values.length > 0) element.Value = values;
@@ -36485,6 +36491,7 @@ var DEFAULT_CONNECTION_TIMEOUT_MS = 1e4;
 var CONNECTION_RETRY_INTERVAL_MS = 500;
 var MAX_CONNECTION_RETRIES = 200;
 var MAX_OUTPUT_LINES_PER_ASSOCIATION = 500;
+var ABORT_REAP_GRACE_MS = 5e3;
 var DicomReceiverOptionsSchema = zod.z.object({
   port: zod.z.number().int().min(0).max(65535),
   storageDir: zod.z.string().min(1).refine(isSafePath, { message: "path traversal detected in storageDir" }),
@@ -36522,6 +36529,9 @@ var Worker = class {
     __publicField(this, "_instancePending", /* @__PURE__ */ new Set());
     __publicField(this, "_instancesReceived", 0);
     __publicField(this, "_instanceErrors", 0);
+    __publicField(this, "_finalized", false);
+    __publicField(this, "_associationReceivedEmitted", false);
+    __publicField(this, "_reapScheduled", false);
     __publicField(this, "_files", []);
     __publicField(this, "_fileSizes", []);
     __publicField(this, "_outputLines", []);
@@ -36562,6 +36572,62 @@ var Worker = class {
     this._instancePending.clear();
     this._instancesReceived = 0;
     this._instanceErrors = 0;
+    this._finalized = false;
+    this._associationReceivedEmitted = false;
+    this._reapScheduled = false;
+  }
+  /**
+   * Claims the single abort-reap timer slot for this association. The socket
+   * `cleanup` handler runs on up to four socket events (remote/worker ×
+   * error/close, plus an explicit setup-race call), so without this guard each
+   * teardown would arm its own redundant grace-period timer. Returns true only
+   * for the first caller; subsequent calls return false and arm nothing.
+   */
+  claimReapSchedule() {
+    if (this._reapScheduled) return false;
+    this._reapScheduled = true;
+    return true;
+  }
+  /** True once per association: the first caller wins the finalize, others get false. */
+  beginFinalizeOnce() {
+    if (this._finalized) return false;
+    this._finalized = true;
+    return true;
+  }
+  /** Whether finalize handling has already been claimed for the current association. */
+  get finalized() {
+    return this._finalized;
+  }
+  /** Records that ASSOCIATION_RECEIVED was emitted to consumers for this association. */
+  markAssociationReceived() {
+    this._associationReceivedEmitted = true;
+  }
+  /**
+   * Whether ASSOCIATION_RECEIVED was emitted for the current association —
+   * i.e. the association was handed off to consumers. When false (a connection
+   * that aborted during/before DICOM negotiation), no consumer ever engaged
+   * with the association directory, so the pool owns its cleanup.
+   */
+  get associationReceived() {
+    return this._associationReceivedEmitted;
+  }
+  /**
+   * Atomically reserves a just-selected idle worker so concurrent connection
+   * routing cannot hand the same worker to two associations. Must be called
+   * synchronously the instant an idle worker is picked — before any `await` —
+   * because `handleConnection` yields (e.g. on `ensureDirectory`) between
+   * selecting a worker and calling {@link beginAssociation}. Without this,
+   * two concurrent connections both see the worker as idle, both proceed, and
+   * the second `beginAssociation` overwrites the first's context — orphaning
+   * the first association (no terminal event ever fires for it). Released via
+   * {@link release} if association setup fails before `beginAssociation`.
+   */
+  reserve() {
+    this._state = "busy";
+  }
+  /** Returns a reserved-but-not-yet-begun worker to the idle pool (setup failed). */
+  release() {
+    this._state = "idle";
   }
   /** Marks the worker as finalizing — still has valid context but cannot accept new connections. */
   markFinalizing() {
@@ -36947,6 +37013,7 @@ var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
     const associationDir = path__namespace.join(this.options.storageDir, associationId);
     const mkdirResult = await ensureDirectory(associationDir);
     if (!mkdirResult.ok) {
+      worker.release();
       remoteSocket.destroy();
       this.emit("error", { error: mkdirResult.error });
       return;
@@ -36965,12 +37032,18 @@ var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
   /** Finds an idle worker, retrying up to connectionTimeoutMs. */
   async findIdleWorker() {
     const idle = this.getIdleWorker();
-    if (idle !== void 0) return idle;
+    if (idle !== void 0) {
+      idle.reserve();
+      return idle;
+    }
     const maxRetries = Math.min(Math.ceil(this.connectionTimeoutMs / CONNECTION_RETRY_INTERVAL_MS), MAX_CONNECTION_RETRIES);
     for (let i = 0; i < maxRetries; i++) {
       await promises.setTimeout(CONNECTION_RETRY_INTERVAL_MS);
       const found = this.getIdleWorker();
-      if (found !== void 0) return found;
+      if (found !== void 0) {
+        found.reserve();
+        return found;
+      }
       if (this.stopping) return void 0;
     }
     return void 0;
@@ -36986,11 +37059,13 @@ var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
   pipeConnection(worker, remoteSocket) {
     const workerSocket = net__namespace.createConnection({ port: worker.port, host: "127.0.0.1" });
     worker.setSockets(remoteSocket, workerSocket);
+    const ctx = worker.context;
     const cleanup = () => {
       remoteSocket.unpipe(workerSocket);
       workerSocket.unpipe(remoteSocket);
       if (!remoteSocket.destroyed) remoteSocket.destroy();
       if (!workerSocket.destroyed) workerSocket.destroy();
+      this.scheduleAbortReap(worker, ctx);
     };
     workerSocket.on("connect", () => {
       remoteSocket.pipe(workerSocket);
@@ -37001,6 +37076,42 @@ var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
     workerSocket.on("error", cleanup);
     remoteSocket.on("close", cleanup);
     workerSocket.on("close", cleanup);
+    if (remoteSocket.destroyed) {
+      cleanup();
+    }
+  }
+  /**
+   * After a connection's sockets tear down, reaps the association as an
+   * aborted one *only if* dcmrecv never reported completion within
+   * {@link ABORT_REAP_GRACE_MS}. Without this, a peer abort destroys the
+   * sockets but dcmrecv may never emit ASSOCIATION_COMPLETE, so the worker
+   * stays busy forever, ASSOCIATION_FINALIZED never fires (consumers can't
+   * release per-association state), and the association directory is never
+   * removed. The grace delay ensures a normal A-RELEASE — whose socket also
+   * closes — is finalized by its own completion report and never reaped here.
+   */
+  scheduleAbortReap(worker, ctx) {
+    if (ctx === void 0 || worker.context !== ctx || worker.state !== "busy") return;
+    if (!worker.claimReapSchedule()) return;
+    const timer = setTimeout(() => {
+      if (worker.context !== ctx || worker.state !== "busy" || worker.finalized) return;
+      worker.markFinalizing();
+      const removeDir = !worker.associationReceived;
+      void this.finalizeAssociation(
+        worker,
+        {
+          associationId: ctx.associationId,
+          callingAE: "",
+          calledAE: "",
+          source: "",
+          files: [],
+          durationMs: Date.now() - ctx.startAt,
+          endReason: "abort"
+        },
+        removeDir
+      );
+    }, ABORT_REAP_GRACE_MS);
+    timer.unref();
   }
   // -----------------------------------------------------------------------
   // Worker pool management
@@ -37199,19 +37310,38 @@ var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
   /** Returns worker to idle pool on association complete, emits summary. */
   wireAssociationComplete(worker) {
     worker.dcmrecv.onAssociationComplete((data) => {
+      if (worker.finalized) return;
       worker.markFinalizing();
+      const removeDir = !worker.associationReceived;
       setImmediate(() => {
-        void this.finalizeAssociation(worker, data);
+        void this.finalizeAssociation(worker, data, removeDir);
       });
     });
   }
-  /** Awaits file ops, emits ASSOCIATION_COMPLETE, awaits parsing, emits ASSOCIATION_FINALIZED. */
-  async finalizeAssociation(worker, data) {
+  /**
+   * Awaits file ops, emits ASSOCIATION_COMPLETE, awaits parsing, emits
+   * ASSOCIATION_FINALIZED, returns the worker to idle. Runs at most once per
+   * association via {@link Worker.beginFinalizeOnce}.
+   *
+   * @param removeDir - When true, removes the association directory after
+   *   finalizing. Set when no consumer ever engaged with the association
+   *   (no ASSOCIATION_RECEIVED was emitted) — e.g. a connection that aborted
+   *   during negotiation — so the pool reclaims the directory it created.
+   *   When a consumer did engage this stays false: the consumer owns
+   *   directory cleanup once it has processed the received files (removing it
+   *   here could race in-flight consumer reads of those files).
+   */
+  async finalizeAssociation(worker, data, removeDir = false) {
+    if (!worker.beginFinalizeOnce()) return;
     await worker.drainPendingFiles();
     this.emitAssociationComplete(worker, data);
     await worker.drainInstancePending();
     this.emitAssociationFinalized(worker, data);
+    const associationDir = worker.context?.associationDir;
     worker.endAssociation();
+    if (removeDir && associationDir !== void 0) {
+      await removeDirSafe(associationDir);
+    }
     void this.scaleDown();
   }
   /** Emits the ASSOCIATION_COMPLETE event with transfer stats. */
@@ -37253,12 +37383,14 @@ var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
       source: data.source,
       files: [...worker.files],
       instancesReceived: worker.instancesReceived,
-      instanceErrors: worker.instanceErrors
+      instanceErrors: worker.instanceErrors,
+      endReason: data.endReason
     });
   }
   /** Bubbles ASSOCIATION_RECEIVED from dcmrecv worker. */
   wireAssociationReceived(worker) {
     worker.dcmrecv.onEvent("ASSOCIATION_RECEIVED", (data) => {
+      worker.markAssociationReceived();
       this.emit("ASSOCIATION_RECEIVED", {
         associationId: worker.context?.associationId ?? "",
         callingAE: data.callingAE,
@@ -37569,7 +37701,12 @@ var SenderEngine = class {
     this.activeAssociations++;
     const startMs = Date.now();
     const maxAttempts = entry.maxRetries + 1;
-    const failure = await this.attemptSend(entry, maxAttempts, startMs);
+    let failure;
+    try {
+      failure = await this.attemptSend(entry, maxAttempts, startMs);
+    } catch (e) {
+      failure = { error: e instanceof Error ? e : new Error(String(e)), output: { stdout: "", stderr: "" } };
+    }
     if (failure === void 0) return;
     this.activeAssociations--;
     this.recordFailure();