@heyocomputer/hws 0.0.0-stage → 0.2.0

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * The admin API's JSON, as types.
+ *
+ * Every field is optional in practice — app-lb omits what is absent and adds
+ * fields over time — so these describe what you *may* find rather than what is
+ * guaranteed. The runtime never validates them: an unknown field is carried
+ * through untouched, which is what makes a client one version behind still work.
+ *
+ * `test/wire-contract.test.ts` reads `testdata/wire/*.json`, written by app-lb's
+ * own response types, and asserts every key in them is declared here. A field
+ * app-lb starts sending fails that test instead of silently going unread.
+ */
+export {};

package/dist/wait.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Waiting for things to converge.
+ *
+ * app-lb answers a build with `202` and a job id, and a spec change immediately
+ * while the pool it describes takes a minute to exist. Both predicates are
+ * fiddly enough that everyone gets them slightly wrong:
+ *
+ *  - a job is done when `status` stops being `running` — but its `log` grows
+ *    while it runs, so progress means tracking what you have already seen;
+ *  - a pool has converged when nothing is pending, enough backends are
+ *    *healthy*, and nothing is draining. Counting `ready` alone reports success
+ *    while a VM is still failing its health check, because `ready` is the size
+ *    of the pool, not the healthy part of it.
+ */
+import type { Heyctl } from "./client.js";
+import type { DeploymentStatus, JobRecord } from "./types.js";
+export declare const JOB_POLL_MS = 3000;
+export declare const POOL_POLL_MS = 2000;
+/**
+ * Where polling starts unless `pollMs` fixes it. It doubles from here up to
+ * {@link JOB_POLL_MS} / {@link POOL_POLL_MS}, so a VM that is ready in half a
+ * second is seen in about that, and a long build is still asked about politely.
+ */
+export declare const FIRST_POLL_MS = 100;
+export interface JobProgress {
+    job: JobRecord;
+    /** Lines that appeared since the last call — not the whole log. */
+    newLog: string[];
+}
+export interface PoolProgress {
+    desired: number;
+    healthy: number;
+    pending: number;
+    draining: number;
+    converged: boolean;
+}
+export interface WaitForJobOptions {
+    /**
+     * Poll through this deployment's job list (`GET /deployments/:id/jobs`)
+     * rather than `GET /jobs/:id`. A namespace token can read the former;
+     * app-lb releases before the namespace-scoped `GET /jobs/:id` refuse it
+     * the latter. Pass `job.deployment` from the record a `start*` call returned.
+     */
+    deployment?: string;
+    pollMs?: number;
+    timeoutMs?: number;
+    onProgress?: (p: JobProgress) => void;
+    signal?: AbortSignal;
+}
+export interface WaitForReadyOptions {
+    pollMs?: number;
+    timeoutMs?: number;
+    onProgress?: (p: PoolProgress) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Poll a job until it finishes.
+ *
+ * Resolves whether it succeeded or failed — a failed job is an answer, not an
+ * error, and its `log` and `error` are the point. Only being unable to *ask*
+ * rejects.
+ */
+export declare function waitForJob(client: Heyctl, jobId: string, opts?: WaitForJobOptions): Promise<JobRecord>;
+/**
+ * Poll a deployment until its pool has converged.
+ *
+ * A `site` or `upstreams` deployment has no pool, so this returns as soon as it
+ * sees one — there is nothing to wait for.
+ */
+export declare function waitForReady(client: Heyctl, id: string, opts?: WaitForReadyOptions): Promise<DeploymentStatus>;

package/dist/wait.js

@@ -0,0 +1,99 @@
+/**
+ * Waiting for things to converge.
+ *
+ * app-lb answers a build with `202` and a job id, and a spec change immediately
+ * while the pool it describes takes a minute to exist. Both predicates are
+ * fiddly enough that everyone gets them slightly wrong:
+ *
+ *  - a job is done when `status` stops being `running` — but its `log` grows
+ *    while it runs, so progress means tracking what you have already seen;
+ *  - a pool has converged when nothing is pending, enough backends are
+ *    *healthy*, and nothing is draining. Counting `ready` alone reports success
+ *    while a VM is still failing its health check, because `ready` is the size
+ *    of the pool, not the healthy part of it.
+ */
+import { NotFoundError, TimeoutError } from "./errors.js";
+export const JOB_POLL_MS = 3_000;
+export const POOL_POLL_MS = 2_000;
+/**
+ * Where polling starts unless `pollMs` fixes it. It doubles from here up to
+ * {@link JOB_POLL_MS} / {@link POOL_POLL_MS}, so a VM that is ready in half a
+ * second is seen in about that, and a long build is still asked about politely.
+ */
+export const FIRST_POLL_MS = 100;
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(t);
+        reject(signal.reason);
+    }, { once: true });
+});
+/**
+ * Poll a job until it finishes.
+ *
+ * Resolves whether it succeeded or failed — a failed job is an answer, not an
+ * error, and its `log` and `error` are the point. Only being unable to *ask*
+ * rejects.
+ */
+export async function waitForJob(client, jobId, opts = {}) {
+    const capMs = opts.pollMs ?? JOB_POLL_MS;
+    let pollMs = opts.pollMs ?? Math.min(FIRST_POLL_MS, capMs);
+    const timeoutMs = opts.timeoutMs ?? 1_800_000;
+    const deadline = Date.now() + timeoutMs;
+    let seen = 0;
+    for (;;) {
+        const job = opts.deployment
+            ? (await client.deploymentJobs(opts.deployment, opts.signal)).find((j) => j.id === jobId)
+            : await client.job(jobId, opts.signal);
+        if (!job)
+            throw new NotFoundError("job", `${jobId} (in deployment ${opts.deployment})`);
+        const log = job.log ?? [];
+        if (opts.onProgress) {
+            // Only the tail is new. app-lb keeps a bounded log, so if it truncated
+            // from the front `seen` can exceed the length — report nothing rather
+            // than a negative slice.
+            opts.onProgress({ job, newLog: log.slice(Math.min(seen, log.length)) });
+        }
+        seen = log.length;
+        if (job.status !== "running")
+            return job;
+        if (Date.now() >= deadline)
+            throw new TimeoutError(`job ${jobId}`, timeoutMs);
+        await sleep(pollMs, opts.signal);
+        pollMs = Math.min(pollMs * 2, capMs);
+    }
+}
+/**
+ * Poll a deployment until its pool has converged.
+ *
+ * A `site` or `upstreams` deployment has no pool, so this returns as soon as it
+ * sees one — there is nothing to wait for.
+ */
+export async function waitForReady(client, id, opts = {}) {
+    const capMs = opts.pollMs ?? POOL_POLL_MS;
+    let pollMs = opts.pollMs ?? Math.min(FIRST_POLL_MS, capMs);
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const status = await client.deployment(id, opts.signal);
+        if (status.kind !== "vm")
+            return status;
+        const vms = status.vms ?? [];
+        const healthy = vms.filter((v) => v.healthy && !v.draining).length;
+        const draining = vms.filter((v) => v.draining).length;
+        const progress = {
+            desired: status.desired_replicas,
+            healthy,
+            pending: status.pending,
+            draining,
+            converged: status.pending === 0 && healthy >= status.desired_replicas && draining === 0,
+        };
+        opts.onProgress?.(progress);
+        if (progress.converged)
+            return status;
+        if (Date.now() >= deadline)
+            throw new TimeoutError(`deployment ${id}`, timeoutMs);
+        await sleep(pollMs, opts.signal);
+        pollMs = Math.min(pollMs * 2, capMs);
+    }
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@heyocomputer/hws",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The app-lb SDK for TypeScript — deployments, autoscaling, exec and shells, rollouts, namespace plugins and telemetry for heyvm microVMs. Twin of the hws crate.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepublishOnly": "npm run build",
+    "e2e": "npm run build && node --test --test-reporter=spec e2e/*.e2e.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependenciesMeta": {},
+  "keywords": [
+    "app-lb",
+    "heyvm",
+    "firecracker",
+    "microvm",
+    "sandbox",
+    "load-balancer",
+    "hws",
+    "heyo"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Heyo-Computer/hws.git",
+    "directory": "app-lb/sdk/typescript"
+  },
+  "homepage": "https://github.com/Heyo-Computer/hws/tree/main/app-lb/sdk/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/Heyo-Computer/hws/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}