@hatchet-dev/typescript-sdk 1.32.0 → 1.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchet-dev/typescript-sdk",
-  "version": "1.32.0",
+  "version": "1.33.1",
   "engines": {
     "node": ">=20"
   },

package/v1/client/worker/health-server.d.ts

@@ -23,6 +23,8 @@ export declare class HealthServer {
     constructor(port: number, getStatus: () => WorkerStatus, workerName: string, getSlots: () => number, getActions: () => string[], getLabels: () => Record<string, string | number>, logger: Logger);
     private handleRequest;
     private handleHealth;
+    private handleReadyz;
+    private handleLivez;
     private initializeMetrics;
     private handleMetrics;
     start(): Promise<void>;

package/v1/client/worker/health-server.js

@@ -40,6 +40,12 @@ class HealthServer {
             if (url === '/health' && req.method === 'GET') {
                 yield this.handleHealth(res);
             }
+            else if (url === '/readyz' && req.method === 'GET') {
+                this.handleReadyz(res);
+            }
+            else if (url === '/livez' && req.method === 'GET') {
+                this.handleLivez(res);
+            }
             else if (url === '/metrics' && req.method === 'GET') {
                 yield this.handleMetrics(res);
             }
@@ -59,10 +65,32 @@ class HealthServer {
                 labels: this.getLabels(),
                 nodeVersion: process.version,
             };
+            // Always return 200 for compatibility with consumers that inspect the JSON
+            // status. Use /readyz when the HTTP status must indicate readiness.
             res.writeHead(200, { 'Content-Type': 'application/json' });
             yield res.end(JSON.stringify(response));
         });
     }
+    // Kubernetes-style readiness probe: 200 only when the worker is HEALTHY
+    // (registered and holding an action listener), 503 otherwise. Unlike
+    // /health, this is a plain status-code contract a vanilla `httpGet` probe
+    // can consume directly, with no body to parse.
+    handleReadyz(res) {
+        const ready = this.getStatus() === exports.workerStatus.HEALTHY;
+        res.writeHead(ready ? 200 : 503, { 'Content-Type': 'text/plain' });
+        res.end(ready ? 'ok' : 'not ready');
+    }
+    // Kubernetes-style liveness probe: 200 whenever this handler can run at
+    // all, deliberately independent of Hatchet connectivity. A worker that has
+    // temporarily lost its action listener (UNHEALTHY) should be pulled from
+    // rotation via /readyz, not killed and restarted via /livez — restarting
+    // does nothing to fix an upstream Hatchet outage and drops in-flight work.
+    // /livez only needs to fail when the process itself is deadlocked/wedged,
+    // which this HTTP response reaching the caller already disproves.
+    handleLivez(res) {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('ok');
+    }
     initializeMetrics() {
         try {
             // THIS IS AN OPTIONAL DEPENDENCY

package/v1/embedded.js

@@ -83,6 +83,46 @@ const net_1 = require("net");
 const promises_1 = require("stream/promises");
 const REPO_URL = 'https://github.com/hatchet-dev/hatchet-embedded';
 const DEFAULT_READY_TIMEOUT_MS = 300000;
+const SLOW_NOTICE_DELAY_MS = 2000;
+const HEARTBEAT_INTERVAL_MS = 30000;
+// first-contact progress goes to stderr (like the engine's own output) so it
+// never corrupts program output; warm starts print at most one line
+function logProgress(message) {
+    process.stderr.write(`hatchet embedded: ${message}\n`);
+}
+// prints startMsg only if fn is still running after SLOW_NOTICE_DELAY_MS (and
+// doneMsg once it finishes), so fast warm-start network calls stay quiet while
+// a blocked one explains what the process is waiting on
+function withSlowNotice(startMsg, doneMsg, fn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        let noticed = false;
+        let finished = false;
+        const timer = setTimeout(() => {
+            // guards a callback already queued when fn settles, so a stale start
+            // message can never print after completion
+            if (finished) {
+                return;
+            }
+            noticed = true;
+            logProgress(startMsg);
+        }, SLOW_NOTICE_DELAY_MS);
+        (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+        let result;
+        try {
+            result = yield fn();
+        }
+        finally {
+            finished = true;
+            clearTimeout(timer);
+        }
+        // only reached when fn succeeded
+        if (noticed) {
+            logProgress(doneMsg);
+        }
+        return result;
+    });
+}
 function sidecarAssetName() {
     const platform = { darwin: 'darwin', linux: 'linux' }[process.platform];
     const arch = { x64: 'amd64', arm64: 'arm64' }[process.arch];
@@ -168,17 +208,18 @@ function resolveExpectedChecksum(tag, asset, binPath) {
 }
 function ensureSidecarBinary(version, checksum) {
     return __awaiter(this, void 0, void 0, function* () {
-        const tag = yield resolveVersion(version);
+        const tag = yield withSlowNotice(`resolving the latest hatchet-embedded release from ${REPO_URL}`, 'resolved the latest hatchet-embedded release', () => resolveVersion(version));
         const asset = sidecarAssetName();
         const binPath = path.join(os.homedir(), '.hatchet', 'embedded', tag, asset);
         yield fs.mkdir(path.dirname(binPath), { recursive: true });
         // verified on every start, not just at download; a cached binary that no
         // longer matches the expected checksum is re-downloaded
-        const expected = checksum !== null && checksum !== void 0 ? checksum : (yield resolveExpectedChecksum(tag, asset, binPath));
+        const expected = checksum !== null && checksum !== void 0 ? checksum : (yield withSlowNotice(`resolving the expected checksum for ${tag} (the cached checksum is used if the release cannot be reached)`, 'expected checksum resolved', () => resolveExpectedChecksum(tag, asset, binPath)));
         const cached = yield fs.access(binPath).then(() => true, () => false);
         if (cached && (yield sha256File(binPath)) === expected) {
             return binPath;
         }
+        logProgress(`downloading the embedded engine sidecar ${tag} to ${binPath} (tens of MB, cached for later runs)`);
         const url = `${REPO_URL}/releases/download/${tag}/${asset}`;
         const res = yield fetch(url);
         if (!res.ok || !res.body) {
@@ -199,12 +240,15 @@ function ensureSidecarBinary(version, checksum) {
         finally {
             yield fs.rm(tmpPath, { force: true });
         }
+        logProgress(`sidecar ${tag} downloaded`);
         return binPath;
     });
 }
 function waitForHandshake(child, handshakePath, timeoutMs) {
     return __awaiter(this, void 0, void 0, function* () {
-        const deadline = Date.now() + timeoutMs;
+        const start = Date.now();
+        const deadline = start + timeoutMs;
+        let nextHeartbeat = start + HEARTBEAT_INTERVAL_MS;
         let exited;
         child.once('exit', (code) => {
             exited = new Error(`hatchet embedded sidecar exited with code ${code} before becoming ready`);
@@ -213,6 +257,11 @@ function waitForHandshake(child, handshakePath, timeoutMs) {
             if (exited) {
                 throw exited;
             }
+            if (Date.now() >= nextHeartbeat) {
+                const elapsed = Math.round((Date.now() - start) / 1000);
+                logProgress(`still waiting for the embedded engine (${elapsed}s elapsed)`);
+                nextHeartbeat += HEARTBEAT_INTERVAL_MS;
+            }
             try {
                 const handshake = JSON.parse(yield fs.readFile(handshakePath, 'utf8'));
                 if (handshake.token) {
@@ -232,6 +281,8 @@ function waitForHandshake(child, handshakePath, timeoutMs) {
 }
 // sidecars started in this process that have not been stopped yet
 const activeSidecars = new Set();
+// the ambient-token warning is printed at most once per process
+let warnedAmbientToken = false;
 /**
  * Gracefully stops every sidecar started in this process by
  * `HatchetEmbeddedClient.init()` (or `startEmbeddedSidecar`) and resolves once
@@ -254,6 +305,10 @@ function stopEmbeddedSidecar() {
 function startEmbeddedSidecar() {
     return __awaiter(this, arguments, void 0, function* (opts = {}) {
         var _a, _b;
+        if (process.env.HATCHET_CLIENT_TOKEN && !warnedAmbientToken) {
+            warnedAmbientToken = true;
+            logProgress('warning: HATCHET_CLIENT_TOKEN is set in the environment. Hatchet clients created with the standard constructor in this process will NOT use the embedded engine; unset HATCHET_CLIENT_TOKEN for embedded runs.');
+        }
         const suppliedPath = (_a = opts.binaryPath) !== null && _a !== void 0 ? _a : process.env.HATCHET_CLIENT_EMBEDDED_BINARY_PATH;
         let binPath;
         if (suppliedPath) {
@@ -299,6 +354,9 @@ function startEmbeddedSidecar() {
         const child = (0, child_process_1.spawn)(binPath, args, { stdio: ['pipe', 'ignore', 'inherit'] });
         const killChild = () => child.kill();
         process.once('exit', killChild);
+        logProgress(opts.databaseUrl
+            ? 'starting the embedded engine'
+            : 'starting the embedded engine (first run initializes a bundled Postgres and can take a minute)');
         let handshake;
         try {
             handshake = yield waitForHandshake(child, handshakePath, (_b = opts.readyTimeoutMs) !== null && _b !== void 0 ? _b : DEFAULT_READY_TIMEOUT_MS);

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.32.0";
+export declare const HATCHET_VERSION = "1.33.1";

package/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HATCHET_VERSION = void 0;
-exports.HATCHET_VERSION = '1.32.0';
+exports.HATCHET_VERSION = '1.33.1';