@xeonr/upload-pool-sdk 1.0.0 → 1.1.0

package/src/rpc-clients.ts

@@ -6,21 +6,64 @@
  *     as the in-band `updateToken` field on each request.
  *   - IntegrationQueueService — accept / complete / report-error.
  *     Auth: the pool token, passed as `queueToken` on each request.
+ *
+ * Each request is wrapped in a logging interceptor that emits one
+ * `rpc.request` line on dispatch and one of `rpc.response` /
+ * `rpc.error` on completion. Latency and connect-error codes are
+ * captured so failed RPCs are diagnosable from worker logs alone.
  */
 import { createConnectTransport } from "@connectrpc/connect-node";
-import { createClient, type Client } from "@connectrpc/connect";
+import {
+	createClient,
+	type Client,
+	type Interceptor,
+	ConnectError,
+	Code,
+} from "@connectrpc/connect";
 import { InternalUploadsService } from "./protocol/uplim/api/v1/uploads_pb.js";
 import { IntegrationQueueService } from "./protocol/uplim/workflow/v1/integration_queue_pb.js";
+import type { Logger } from "./logger.js";
 
 export interface RpcClients {
 	internalUploads: Client<typeof InternalUploadsService>;
 	integrationQueue: Client<typeof IntegrationQueueService>;
 }
 
-export function createRpcClients(endpoint: string): RpcClients {
+function loggingInterceptor(logger: Logger): Interceptor {
+	return (next) => async (req) => {
+		const startedAt = Date.now();
+		const method = `${req.service.typeName}/${req.method.name}`;
+		logger.debug("rpc.request", { method });
+		try {
+			const res = await next(req);
+			logger.debug("rpc.response", {
+				method,
+				durationMs: Date.now() - startedAt,
+			});
+			return res;
+		} catch (err) {
+			const code =
+				err instanceof ConnectError ? Code[err.code] : undefined;
+			const message = err instanceof Error ? err.message : String(err);
+			logger.error("rpc.error", {
+				method,
+				code,
+				message,
+				durationMs: Date.now() - startedAt,
+			});
+			throw err;
+		}
+	};
+}
+
+export function createRpcClients(
+	endpoint: string,
+	logger: Logger,
+): RpcClients {
 	const transport = createConnectTransport({
 		baseUrl: endpoint,
 		httpVersion: "1.1",
+		interceptors: [loggingInterceptor(logger.child({ component: "rpc" }))],
 	});
 	return {
 		internalUploads: createClient(InternalUploadsService, transport),

package/src/sse-client.ts

@@ -5,14 +5,21 @@
  *
  * 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";
+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;
@@ -25,6 +32,8 @@ export class SseClient {
 	private es: EventSource | null = null;
 	private stopped = false;
 	private reconnectDelay = RECONNECT_INITIAL_MS;
+	private connectAttempt = 0;
+	private connectedAt: number | null = null;
 
 	constructor(private readonly config: SseClientConfig) {}
 
@@ -39,11 +48,13 @@ export class SseClient {
 			this.es.close();
 			this.es = null;
 		}
+		this.config.logger.info("sse.stopped");
 	}
 
 	private connect(): void {
 		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);
@@ -51,31 +62,84 @@ export class SseClient {
 			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 as MessageEvent).data);
+				this.config.logger.debug("sse.event.job_dispatch", {
+					jobId: (data as { jobId?: string }).jobId,
+				});
 				this.config.onJobDispatch(data);
 			} catch (err) {
-				this.config.onDisconnected(`bad job payload: ${(err as Error).message}`);
+				const reason = `bad job payload: ${(err as Error).message}`;
+				this.config.logger.error("sse.event.parse_error", {
+					err,
+					rawData: (event as MessageEvent).data,
+				});
+				this.config.onDisconnected(reason);
 			}
 		});
 
-		// heartbeat events are no-ops — receipt alone keeps the connection alive.
+		// 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 = () => {
+		this.es.onerror = (err: unknown) => {
 			if (this.stopped) return;
-			this.config.onDisconnected("sse error");
+			const errMessage =
+				(err as { message?: string; type?: string; status?: number })?.message ??
+				(err as { type?: string })?.type ??
+				"unknown";
+			const status = (err as { status?: number; code?: number })?.status ??
+				(err as { code?: number })?.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;
 			}
+
 			setTimeout(() => this.connect(), this.reconnectDelay);
 			this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
 		};

package/src/types.ts

@@ -25,8 +25,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;
 }