npm - @xeonr/upload-pool-sdk - Versions diffs - 1.0.0 → 1.1.0 - Mend

@xeonr/upload-pool-sdk 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/dist/rpc-clients.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"rpc-clients.js","sourceRoot":"","sources":["../src/rpc-clients.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;GAQG~~;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,~~EAAE~~,YAAY,~~EAAe~~,MAAM,qBAAqB,CAAC;~~AAChE~~,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sDAAsD,CAAC;~~AAO~~/F,MAAM,UAAU,~~gBAAgB~~,CAAC,QAAgB;~~IAChD~~,MAAM,SAAS,GAAG,sBAAsB,CAAC;QACxC,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,KAAK;~~KAClB~~,CAAC,CAAC;IACH,OAAO;QACN,eAAe,EAAE,YAAY,CAAC,sBAAsB,EAAE,SAAS,CAAC;QAChE,gBAAgB,EAAE,YAAY,CAAC,uBAAuB,EAAE,SAAS,CAAC;KAClE,CAAC;AACH,CAAC"}
1	+ {"version":3,"file":"rpc-clients.js","sourceRoot":"","sources":["../src/rpc-clients.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACN,YAAY,EAGZ,YAAY,EACZ,IAAI,GACJ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sDAAsD,CAAC;AAQ/F,SAAS,kBAAkB,CAAC,MAAc;IACzC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5D,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE;gBAC5B,MAAM;gBACN,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aAClC,CAAC,CAAC;YACH,OAAO,GAAG,CAAC;QACZ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,GACT,GAAG,YAAY,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1D,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE;gBACzB,MAAM;gBACN,IAAI;gBACJ,OAAO;gBACP,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aAClC,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACX,CAAC;IACF,CAAC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,QAAgB,EAChB,MAAc;IAEd,MAAM,SAAS,GAAG,sBAAsB,CAAC;QACxC,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;KACtE,CAAC,CAAC;IACH,OAAO;QACN,eAAe,EAAE,YAAY,CAAC,sBAAsB,EAAE,SAAS,CAAC;QAChE,gBAAgB,EAAE,YAAY,CAAC,uBAAuB,EAAE,SAAS,CAAC;KAClE,CAAC;AACH,CAAC"}

package/dist/sse-client.d.ts CHANGED Viewed

@@ -1,8 +1,10 @@
+import type { Logger } from "./logger.js";
 export interface SseClientConfig {
     endpoint: string;
     token: string;
     workerId: string;
     capabilities: string[];
+    logger: Logger;
     onConnected: () => void;
     onDisconnected: (reason: string) => void;
     onJobDispatch: (payload: unknown) => void;
@@ -12,6 +14,8 @@ export declare class SseClient {
     private es;
     private stopped;
     private reconnectDelay;
+    private connectAttempt;
+    private connectedAt;
     constructor(config: SseClientConfig);
     start(): void;
     stop(): void;

package/dist/sse-client.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"sse-client.d.ts","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"~~AAUA~~,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAKD,qBAAa,SAAS;~~IAKT~~,OAAO,CAAC,QAAQ,CAAC,MAAM;~~IAJnC~~,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAwB;~~gBAEjB~~,MAAM,EAAE,eAAe;IAEpD,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI;~~IAQZ~~,OAAO,CAAC,OAAO;~~CAuCf~~"}
1	+ {"version":3,"file":"sse-client.d.ts","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAKD,qBAAa,SAAS;IAOT,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAuB;gBAEb,MAAM,EAAE,eAAe;IAEpD,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI;IASZ,OAAO,CAAC,OAAO;CA6Ff"}

package/dist/sse-client.js CHANGED Viewed

@@ -5,6 +5,11 @@
  *
  * Reconnect strategy: exponential backoff (1s, 2s, 4s, 8s, capped at 30s).
  * On `job:dispatch` events the SDK invokes the registered onJob callback.
+ *
+ * All lifecycle transitions emit structured logs via the injected
+ * `Logger` so connection failures are visible in the worker's k8s logs
+ * (otherwise a worker that can't connect at all looks identical to one
+ * that's idle).
  */
 import { EventSource } from "eventsource";
 const RECONNECT_INITIAL_MS = 1_000;
@@ -14,6 +19,8 @@ export class SseClient {
     es = null;
     stopped = false;
     reconnectDelay = RECONNECT_INITIAL_MS;
+    connectAttempt = 0;
+    connectedAt = null;
     constructor(config) {
         this.config = config;
     }
@@ -27,35 +34,82 @@ export class SseClient {
             this.es.close();
             this.es = null;
         }
+        this.config.logger.info("sse.stopped");
     }
     connect() {
         if (this.stopped)
             return;
+        this.connectAttempt++;
         const url = new URL(`${this.config.endpoint}/queue/connect`);
         url.searchParams.set("queueToken", this.config.token);
         url.searchParams.set("workerId", this.config.workerId);
         if (this.config.capabilities.length > 0) {
             url.searchParams.set("capabilities", this.config.capabilities.join(","));
         }
+        // Strip the token from the logged URL — the queueToken param is the
+        // pool secret, no reason to bake it into telemetry.
+        const loggedUrl = new URL(url.toString());
+        loggedUrl.searchParams.set("queueToken", "[redacted]");
+        this.config.logger.info("sse.connect.start", {
+            url: loggedUrl.toString(),
+            attempt: this.connectAttempt,
+            capabilities: this.config.capabilities,
+        });
         this.es = new EventSource(url.toString());
+        this.es.addEventListener("open", () => {
+            this.config.logger.debug("sse.open");
+        });
         this.es.addEventListener("connected", () => {
             this.reconnectDelay = RECONNECT_INITIAL_MS;
+            this.connectedAt = Date.now();
+            this.config.logger.info("sse.connect.opened", {
+                attempt: this.connectAttempt,
+            });
             this.config.onConnected();
         });
         this.es.addEventListener("job:dispatch", (event) => {
             try {
                 const data = JSON.parse(event.data);
+                this.config.logger.debug("sse.event.job_dispatch", {
+                    jobId: data.jobId,
+                });
                 this.config.onJobDispatch(data);
             }
             catch (err) {
-                this.config.onDisconnected(`bad job payload: ${err.message}`);
+                const reason = `bad job payload: ${err.message}`;
+                this.config.logger.error("sse.event.parse_error", {
+                    err,
+                    rawData: event.data,
+                });
+                this.config.onDisconnected(reason);
             }
         });
-        // heartbeat events are no-ops — receipt alone keeps the connection alive.
-        this.es.onerror = () => {
+        // heartbeat events are no-ops at the dispatch layer — receipt alone
+        // keeps the connection alive. We log at debug so noisy keep-alive
+        // traffic doesn't drown the info stream.
+        this.es.addEventListener("heartbeat", () => {
+            this.config.logger.debug("sse.event.heartbeat");
+        });
+        this.es.onerror = (err) => {
             if (this.stopped)
                 return;
-            this.config.onDisconnected("sse error");
+            const errMessage = err?.message ??
+                err?.type ??
+                "unknown";
+            const status = err?.status ??
+                err?.code;
+            const wasConnected = this.connectedAt !== null;
+            const uptimeMs = wasConnected ? Date.now() - this.connectedAt : null;
+            this.config.logger.warn("sse.disconnected", {
+                message: errMessage,
+                status,
+                wasConnected,
+                uptimeMs,
+                attempt: this.connectAttempt,
+                nextReconnectMs: this.reconnectDelay,
+            });
+            this.config.onDisconnected(`sse error: ${errMessage}`);
+            this.connectedAt = null;
             if (this.es) {
                 this.es.close();
                 this.es = null;

package/dist/sse-client.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"sse-client.js","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"AAAA~~;;;;;;;GAOG~~;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;~~AAY1C~~,MAAM,oBAAoB,GAAG,KAAK,CAAC;AACnC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC,MAAM,OAAO,SAAS;~~IAKQ~~;~~IAJrB~~,EAAE,GAAuB,IAAI,CAAC;IAC9B,OAAO,GAAG,KAAK,CAAC;IAChB,cAAc,GAAG,oBAAoB,CAAC;~~IAE9C~~,YAA6B,MAAuB;QAAvB,WAAM,GAAN,MAAM,CAAiB;IAAG,CAAC;IAExD,KAAK;QACJ,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,IAAI;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QAChB,CAAC;~~IACF~~,CAAC;IAEO,OAAO;QACd,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAEzB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,gBAAgB,CAAC,CAAC;QAC7D,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,EAAE,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE1C,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE;YAC1C,IAAI,CAAC,cAAc,GAAG,oBAAoB,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE;YAClD,IAAI,CAAC;gBACJ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAE,KAAsB,CAAC,IAAI,CAAC,CAAC;gBACtD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,IAAI,CAAC,MAAM,CAAC,~~cAAc~~,CAAC,~~oBAAqB~~,~~GAAa,~~CAAC,~~OAAO~~,EAAE,CAAC,CAAC;~~YAC1E~~,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,~~0EAA0E~~;~~QAE1E~~,IAAI,CAAC,EAAE,CAAC,~~OAAO~~,GAAG,GAAG,EAAE;~~YACtB~~,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YACzB,IAAI,CAAC,MAAM,CAAC,~~cAAc~~,CAAC,WAAW,CAAC,CAAC;~~YACxC~~,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;gBAChB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;YAChB,CAAC;~~YACD~~,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YACtD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAC3E,CAAC,CAAC;IACH,CAAC;CACD"}
1	+ {"version":3,"file":"sse-client.js","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc1C,MAAM,oBAAoB,GAAG,KAAK,CAAC;AACnC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC,MAAM,OAAO,SAAS;IAOQ;IANrB,EAAE,GAAuB,IAAI,CAAC;IAC9B,OAAO,GAAG,KAAK,CAAC;IAChB,cAAc,GAAG,oBAAoB,CAAC;IACtC,cAAc,GAAG,CAAC,CAAC;IACnB,WAAW,GAAkB,IAAI,CAAC;IAE1C,YAA6B,MAAuB;QAAvB,WAAM,GAAN,MAAM,CAAiB;IAAG,CAAC;IAExD,KAAK;QACJ,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC;IAED,IAAI;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IAEO,OAAO;QACd,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAEzB,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,gBAAgB,CAAC,CAAC;QAC7D,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1E,CAAC;QAED,oEAAoE;QACpE,oDAAoD;QACpD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1C,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAEvD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC5C,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE;YACzB,OAAO,EAAE,IAAI,CAAC,cAAc;YAC5B,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;SACtC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE1C,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;YACrC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE;YAC1C,IAAI,CAAC,cAAc,GAAG,oBAAoB,CAAC;YAC3C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE;gBAC7C,OAAO,EAAE,IAAI,CAAC,cAAc;aAC5B,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE;YAClD,IAAI,CAAC;gBACJ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAE,KAAsB,CAAC,IAAI,CAAC,CAAC;gBACtD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE;oBAClD,KAAK,EAAG,IAA2B,CAAC,KAAK;iBACzC,CAAC,CAAC;gBACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,MAAM,MAAM,GAAG,oBAAqB,GAAa,CAAC,OAAO,EAAE,CAAC;gBAC5D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE;oBACjD,GAAG;oBACH,OAAO,EAAG,KAAsB,CAAC,IAAI;iBACrC,CAAC,CAAC;gBACH,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YACpC,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,oEAAoE;QACpE,kEAAkE;QAClE,yCAAyC;QACzC,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE;YAC1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,CAAC,GAAY,EAAE,EAAE;YAClC,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YACzB,MAAM,UAAU,GACd,GAA4D,EAAE,OAAO;gBACrE,GAAyB,EAAE,IAAI;gBAChC,SAAS,CAAC;YACX,MAAM,MAAM,GAAI,GAA0C,EAAE,MAAM;gBAChE,GAAyB,EAAE,IAAI,CAAC;YAClC,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC;YAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAY,CAAC,CAAC,CAAC,IAAI,CAAC;YAEtE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE;gBAC3C,OAAO,EAAE,UAAU;gBACnB,MAAM;gBACN,YAAY;gBACZ,QAAQ;gBACR,OAAO,EAAE,IAAI,CAAC,cAAc;gBAC5B,eAAe,EAAE,IAAI,CAAC,cAAc;aACpC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,cAAc,UAAU,EAAE,CAAC,CAAC;YACvD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YAExB,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;gBAChB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;YAChB,CAAC;YAED,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YACtD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAC3E,CAAC,CAAC;IACH,CAAC;CACD"}

package/dist/types.d.ts CHANGED Viewed

@@ -24,8 +24,21 @@ export interface PoolConfig {
     handlers: Record<string, JobHandler>;
     /** Fallback handler if URN has no specific entry in `handlers`. Optional. */
     onUnhandled?: JobHandler;
-    /** Lifecycle / error hook. Defaults to console-based logging. */
+    /**
+     * Lifecycle / error hook. Receives every handler exception alongside
+     * the job context. The SDK also logs every failure via `logger` —
+     * `onError` is for hooks that need to fan out to external systems
+     * (sentry, pagerduty). Optional.
+     */
     onError?: (err: Error, ctx?: JobContext) => void;
+    /**
+     * Structured logger. Defaults to a JSON-line logger that writes to
+     * stdout (`info`/`debug`) and stderr (`warn`/`error`), honoring
+     * `UPL_LOG_LEVEL`. Pass `noopLogger` from this package for silence,
+     * or supply your own implementing the `Logger` interface to bridge
+     * to pino/winston.
+     */
+    logger?: import("./logger.js").Logger;
     /** Max concurrent in-flight jobs. Defaults to 1. */
     concurrency?: number;
 }

package/dist/types.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,UAAU;IAC1B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,6EAA6E;IAC7E,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB~~,iEAAiE~~;~~IACjE~~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"}
1	+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@xeonr/upload-pool-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Self-hosted worker SDK for the upl.im content type pipeline. Implement a handler per content type URN; the SDK handles SSE connection, job acceptance, presigned thumbnail upload, and metadata callbacks.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts CHANGED Viewed

@@ -23,6 +23,8 @@ import type { PoolConfig } from "./types.js";
 export { Pool } from "./pool.js";
 export { NonRetryableError } from "./errors.js";
+export { JsonLogger, noopLogger } from "./logger.js";
+export type { Logger, LogLevel } from "./logger.js";
 export type {
 	PoolConfig,
 	JobContext,

package/src/job-context.ts CHANGED Viewed

@@ -17,6 +17,7 @@ import {
 } from "./protocol/uplim/api/v1/uploads_pb.js";
 import { UploadMetadataSchema } from "./protocol/uplim/api/v1/metadata_pb.js";
 import type { RpcClients } from "./rpc-clients.js";
+import type { Logger } from "./logger.js";
 import type {
 	FolderContext,
 	JobContext,
@@ -54,6 +55,7 @@ export interface JobEnvelope {
 export function createJobContext(
 	envelope: JobEnvelope,
 	rpc: RpcClients,
+	logger: Logger,
 ): JobContext {
 	const ctx: JobContext = {
 		jobId: envelope.jobId,
@@ -71,28 +73,45 @@ export function createJobContext(
 		sourceUrl: envelope.sourceUrl,
 		async download() {
+			logger.debug("source.download.start");
 			const resp = await fetch(envelope.sourceUrl);
 			if (!resp.ok || !resp.body) {
+				logger.error("source.download.failed", {
+					status: resp.status,
+					statusText: resp.statusText,
+				});
 				throw new Error(`source download failed: ${resp.status} ${resp.statusText}`);
 			}
 			return resp.body;
 		},
 		async downloadBuffer() {
+			logger.debug("source.download.start", { mode: "buffer" });
 			const resp = await fetch(envelope.sourceUrl);
 			if (!resp.ok) {
+				logger.error("source.download.failed", {
+					status: resp.status,
+					statusText: resp.statusText,
+				});
 				throw new Error(`source download failed: ${resp.status} ${resp.statusText}`);
 			}
 			const buf = await resp.arrayBuffer();
+			logger.debug("source.download.complete", { sizeBytes: buf.byteLength });
 			return new Uint8Array(buf);
 		},
 		async downloadToFile(path: string) {
 			const data = await ctx.downloadBuffer();
 			await writeFile(path, data);
+			logger.debug("source.download.to_file", { path, sizeBytes: data.byteLength });
 		},
 		async uploadMeta(opts: UploadMetaOpts) {
+			logger.debug("meta.upload.start", {
+				type: opts.type,
+				instance: opts.instance,
+				filename: opts.filename,
+			});
 			const protoType = META_TYPE_MAP[opts.type];
 			const metaType = create(MetaTypeSchema, {
 				type: protoType,
@@ -135,6 +154,10 @@ export function createJobContext(
 					metadataId: [meta.metadataId],
 				}),
 			);
+			logger.info("meta.upload.complete", {
+				type: opts.type,
+				metadataId: meta.metadataId,
+			});
 		},
 		async setMetadata(metadata: UploadMetadataPartial | UploadMetadataProto) {
@@ -163,6 +186,7 @@ export function createJobContext(
 					thumbnailGenerationVersion: thumbnailVersion,
 				}),
 			);
+			logger.debug("metadata.set", { thumbnailVersion });
 		},
 		async markHasThumbnail(version: number) {
@@ -173,6 +197,7 @@ export function createJobContext(
 					thumbnailGenerationVersion: version,
 				}),
 			);
+			logger.info("thumbnail.marked", { version });
 		},
 		async setDescription(text: string, tags?: string[]) {
@@ -185,12 +210,20 @@ export function createJobContext(
 					}),
 				}),
 			);
+			logger.info("description.set", {
+				length: text.length,
+				tags: tags?.length ?? 0,
+			});
 		},
 		async withPresignedUploads<T>(
 			opts: PresignedUploadRequest[],
 			callback: (handles: import("./types.js").MetaUploadHandle[]) => Promise<T>,
 		): Promise<T> {
+			logger.debug("presigned.upload.request", {
+				count: opts.length,
+				types: opts.map((o) => o.type),
+			});
 			const metaTypes = opts.map((opt) => create(MetaTypeSchema, {
 				type: META_TYPE_MAP[opt.type],
 				n: opt.instance,
@@ -222,6 +255,7 @@ export function createJobContext(
 					metadataId: requested.metaUploads.map((m) => m.metadataId),
 				}),
 			);
+			logger.info("presigned.upload.complete", { count: handles.length });
 			return result;
 		},
 	};

package/src/logger.ts ADDED Viewed

@@ -0,0 +1,159 @@
+/**
+ * Logging interface for the SDK. Customers can plug in their own
+ * logger (pino, winston, console) by passing `logger` to createPool;
+ * by default we emit structured JSON lines to stdout/stderr so logs
+ * are grep-friendly in k8s.
+ *
+ * The shape mirrors the pipeline-api's logger contract for consistency
+ * across the upl.im stack.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface Logger {
+	debug(event: string, context?: Record<string, unknown>): void;
+	info(event: string, context?: Record<string, unknown>): void;
+	warn(event: string, context?: Record<string, unknown>): void;
+	error(event: string, context?: Record<string, unknown>): void;
+	/**
+	 * Return a derived logger that merges these context fields into every
+	 * subsequent log call. Used by Pool.handleDispatch to attach jobId /
+	 * uploadId / urn to every line emitted during the job.
+	 */
+	child(context: Record<string, unknown>): Logger;
+}
+const SENSITIVE_KEYS = new Set([
+	"token",
+	"queueToken",
+	"queue_token",
+	"workerToken",
+	"worker_token",
+	"updateToken",
+	"update_token",
+	"authorization",
+	"Authorization",
+]);
+/**
+ * Redact obvious secrets so a careless `logger.info("rpc.request", { headers })`
+ * doesn't leak the pool token to log aggregators. Best-effort; not a
+ * substitute for thinking about what you're logging.
+ */
+function redact(value: unknown): unknown {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			if (SENSITIVE_KEYS.has(k)) {
+				out[k] = typeof v === "string" && v.length > 8
+					? `${v.slice(0, 4)}…(${v.length - 4} redacted)`
+					: "[redacted]";
+			} else if (v && typeof v === "object") {
+				out[k] = redact(v);
+			} else {
+				out[k] = v;
+			}
+		}
+		return out;
+	}
+	if (Array.isArray(value)) return value.map(redact);
+	return value;
+}
+function serializeError(err: unknown): Record<string, unknown> {
+	if (err instanceof Error) {
+		return {
+			name: err.name,
+			message: err.message,
+			stack: err.stack,
+			...(err as unknown as Record<string, unknown>),
+		};
+	}
+	return { value: String(err) };
+}
+/**
+ * Default JSON logger. Emits one line per call. `error` and `warn` go to
+ * stderr; `info` and `debug` go to stdout. Honors `UPL_LOG_LEVEL` env var
+ * (`debug` | `info` | `warn` | `error`) to filter out noise in prod.
+ */
+export class JsonLogger implements Logger {
+	private readonly base: Record<string, unknown>;
+	private readonly minLevel: LogLevel;
+	constructor(base: Record<string, unknown> = {}, minLevel?: LogLevel) {
+		this.base = base;
+		this.minLevel = minLevel ?? (process.env.UPL_LOG_LEVEL as LogLevel) ?? "info";
+	}
+	child(context: Record<string, unknown>): Logger {
+		return new JsonLogger({ ...this.base, ...context }, this.minLevel);
+	}
+	debug(event: string, context?: Record<string, unknown>): void {
+		this.emit("debug", event, context);
+	}
+	info(event: string, context?: Record<string, unknown>): void {
+		this.emit("info", event, context);
+	}
+	warn(event: string, context?: Record<string, unknown>): void {
+		this.emit("warn", event, context);
+	}
+	error(event: string, context?: Record<string, unknown>): void {
+		this.emit("error", event, context);
+	}
+	private shouldEmit(level: LogLevel): boolean {
+		const order: Record<LogLevel, number> = {
+			debug: 10,
+			info: 20,
+			warn: 30,
+			error: 40,
+		};
+		return order[level] >= order[this.minLevel];
+	}
+	private emit(
+		level: LogLevel,
+		event: string,
+		context?: Record<string, unknown>,
+	): void {
+		if (!this.shouldEmit(level)) return;
+		const merged: Record<string, unknown> = {
+			...this.base,
+			...(context ? (redact(context) as Record<string, unknown>) : {}),
+		};
+		if (merged.err !== undefined) {
+			merged.err = serializeError(merged.err);
+		}
+		if (merged.error !== undefined && merged.error instanceof Error) {
+			merged.error = serializeError(merged.error);
+		}
+		const line = JSON.stringify({
+			ts: new Date().toISOString(),
+			level,
+			logger: "@xeonr/upload-pool-sdk",
+			event,
+			...merged,
+		});
+		// eslint-disable-next-line no-console
+		(level === "error" || level === "warn" ? console.error : console.log)(line);
+	}
+}
+/**
+ * No-op logger for tests or callers who want silence. createPool ignores
+ * this if `logger` is unset and uses JsonLogger by default.
+ */
+export const noopLogger: Logger = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {},
+	child() {
+		return noopLogger;
+	},
+};

package/src/pool.ts CHANGED Viewed

@@ -3,6 +3,11 @@
  * to the pool's job stream, dispatches job:dispatch events to the right
  * handler keyed by content type URN, and orchestrates accept/complete/
  * report-error against IntegrationQueueService.
+ *
+ * Every transition emits a structured log line via the injected Logger
+ * so a worker's k8s logs surface SSE connection state, dispatched jobs,
+ * handler outcomes, and RPC errors without callers needing to wire up
+ * their own onError hook.
  */
 import { hostname } from "node:os";
 import { randomBytes } from "node:crypto";
@@ -16,6 +21,7 @@ import { createRpcClients, type RpcClients } from "./rpc-clients.js";
 import { SseClient } from "./sse-client.js";
 import { createJobContext, type JobEnvelope } from "./job-context.js";
 import { NonRetryableError } from "./errors.js";
+import { JsonLogger, type Logger } from "./logger.js";
 import type {
 	JobContext,
 	JobHandler,
@@ -26,6 +32,7 @@ export class Pool {
 	private readonly config: PoolConfig;
 	private readonly rpc: RpcClients;
 	private readonly sse: SseClient;
+	private readonly logger: Logger;
 	private inFlight = 0;
 	private readonly workerId: string;
 	private readonly capabilities: string[];
@@ -33,46 +40,80 @@ export class Pool {
 	constructor(config: PoolConfig) {
 		this.config = {
 			concurrency: 1,
-			onError: defaultErrorHandler,
 			...config,
 		};
 		this.workerId = config.workerId ?? `${hostname()}-${randomBytes(4).toString("hex")}`;
 		this.capabilities = Object.keys(config.handlers);
-		this.rpc = createRpcClients(config.endpoint);
+		this.logger = (config.logger ?? new JsonLogger()).child({
+			workerId: this.workerId,
+		});
+		this.rpc = createRpcClients(config.endpoint, this.logger);
 		this.sse = new SseClient({
 			endpoint: config.endpoint,
 			token: config.token,
 			workerId: this.workerId,
 			capabilities: this.capabilities,
+			logger: this.logger.child({ component: "sse" }),
 			onConnected: () => {
-				/* lifecycle: future event emitter hook */
+				/* logged inside sse-client; callers can hook lifecycle here later */
 			},
 			onDisconnected: () => {
-				/* lifecycle: future event emitter hook */
+				/* logged inside sse-client */
 			},
 			onJobDispatch: (payload) => this.handleDispatch(payload as JobEnvelope),
 		});
+		this.logger.info("sdk.boot", {
+			endpoint: config.endpoint,
+			capabilities: this.capabilities,
+			concurrency: this.config.concurrency,
+			version: SDK_VERSION,
+		});
+		if (this.capabilities.length === 0) {
+			this.logger.warn("sdk.boot.no_handlers", {
+				note: "no handlers registered — worker will not receive any jobs",
+			});
+		}
 	}
 	async start(): Promise<void> {
+		this.logger.info("sdk.start");
 		this.sse.start();
 	}
 	async stop(): Promise<void> {
+		this.logger.info("sdk.stop", { inFlight: this.inFlight });
 		this.sse.stop();
 	}
 	private async handleDispatch(envelope: JobEnvelope): Promise<void> {
+		const jobLogger = this.logger.child({
+			jobId: envelope.jobId,
+			uploadId: envelope.uploadId,
+			urn: envelope.contentTypeContext.urn,
+		});
 		if (this.inFlight >= (this.config.concurrency ?? 1)) {
 			// Pipeline only dispatches to idle workers (zero in-flight), so
 			// this branch is defensive — if it ever fires we silently
 			// drop the dispatch and let the pipeline timeout requeue.
+			jobLogger.warn("job.dispatched.dropped_at_capacity", {
+				inFlight: this.inFlight,
+				concurrency: this.config.concurrency,
+			});
 			return;
 		}
 		this.inFlight++;
+		jobLogger.info("job.dispatched", {
+			filename: envelope.filename,
+			mimeType: envelope.mimeType,
+			inFlight: this.inFlight,
+		});
 		const handler = this.resolveHandler(envelope.contentTypeContext.urn);
-		const ctx = createJobContext(envelope, this.rpc);
+		const ctx = createJobContext(envelope, this.rpc, jobLogger);
+		const startedAt = Date.now();
 		try {
 			// AcceptJob — clears the pipeline's accept-timeout.
@@ -83,11 +124,16 @@ export class Pool {
 					queueToken: this.config.token,
 				}),
 			);
+			jobLogger.info("job.accepted");
 			if (!handler) {
+				jobLogger.warn("job.unhandled", {
+					availableHandlers: this.capabilities,
+				});
 				await this.reportError(
 					envelope.jobId,
 					ctx,
+					jobLogger,
 					new NonRetryableError(`no handler for URN ${envelope.contentTypeContext.urn}`),
 				);
 				return;
@@ -102,8 +148,15 @@ export class Pool {
 					queueToken: this.config.token,
 				}),
 			);
+			jobLogger.info("job.completed", {
+				durationMs: Date.now() - startedAt,
+			});
 		} catch (err) {
-			await this.reportError(envelope.jobId, ctx, err as Error);
+			jobLogger.error("job.failed", {
+				err,
+				durationMs: Date.now() - startedAt,
+			});
+			await this.reportError(envelope.jobId, ctx, jobLogger, err as Error);
 		} finally {
 			this.inFlight--;
 		}
@@ -116,6 +169,7 @@ export class Pool {
 	private async reportError(
 		jobId: string,
 		ctx: JobContext,
+		jobLogger: Logger,
 		err: Error,
 	): Promise<void> {
 		const retry = !(err instanceof NonRetryableError);
@@ -130,14 +184,12 @@ export class Pool {
 					retry,
 				}),
 			);
+			jobLogger.info("job.error_reported", { retry });
 		} catch (rptErr) {
+			jobLogger.error("job.error_report_failed", { err: rptErr });
 			this.config.onError?.(rptErr as Error, ctx);
 		}
 	}
 }
-function defaultErrorHandler(err: Error, ctx?: JobContext): void {
-	const where = ctx ? `job ${ctx.jobId} (${ctx.contentType.urn})` : "pool";
-	// eslint-disable-next-line no-console
-	console.error(`[@xeonr/upload-pool-sdk] ${where}: ${err.message}`);
-}
+const SDK_VERSION = "1.1.0";