@zgeoff/imp-client 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoff Whatley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @zgeoff/imp-client
+
+A typed client for [impd](https://github.com/zgeoff/imp), the imp host daemon. It runs in Bun, in
+Node 22 or later, and in browsers with `Promise.withResolvers`: Chrome 119, Firefox 121 and Safari
+17.4 or later.
+
+```sh
+npm install @zgeoff/imp-client
+```
+
+`@opentelemetry/api` is an optional peer: oRPC's type declarations name it, so a project that
+type-checks its dependencies (no `skipLibCheck`) installs it too.
+
+## Connect
+
+```ts
+import { createImpClient } from '@zgeoff/imp-client';
+
+const imp = createImpClient({
+  url: 'http://localhost:7070',
+  token: process.env.IMP_TOKEN,
+});
+```
+
+- `url` is impd's API. A path prefix is kept, so impd can sit behind a proxy at `/impd/`.
+- `token` is the bearer token from `<IMP_DATA_DIR>/token`. It controls every imp on the host, so
+  keep it on a server. A browser app sends its requests through a proxy that adds the token, and
+  leaves `token` out.
+- `fetch` swaps the transport, for example to call an in-process app in tests.
+
+## Imps, checkpoints and forks
+
+Every procedure of impd's API is on the client, with its input and output types.
+
+```ts
+const dev = await imp.imps.create({ name: 'dev', memoryMib: 2048 });
+
+const checkpoint = await imp.checkpoints.create({ name: 'dev', label: 'clean' });
+
+// a new imp from the checkpoint's disk
+await imp.imps.fork({ source: 'dev', name: 'dev-2', checkpoint: checkpoint.id });
+
+await imp.imps.sleep({ name: 'dev' });
+```
+
+`imp.requireAwake(name)` makes one wake call. It wakes a sleeping imp, boots a stopped one and
+returns a running one as it is. impd refuses an imp in the `error` state with `INVALID_STATE`,
+because a wake would restart it; pass `{ restartError: true }` to restart it anyway. While impd
+stops, calls fail with `SERVICE_UNAVAILABLE`, and while it restarts, `fetch` cannot connect; pass
+`{ retryUnavailable: { attempts, delayMs } }` to wait for it to come back. `RAM_BUDGET_EXCEEDED` is
+never retried.
+
+## Run commands
+
+`imp.run` runs a command to its exit and collects its output. Without `stdin`, stdin closes at once.
+
+```ts
+const result = await imp.run('dev', ['sh', '-c', 'uname -a; cat'], { stdin: 'hi\n' });
+
+console.log(result.code, new TextDecoder().decode(result.stdout));
+```
+
+`imp.openExec` streams instead. `stdout` and `stderr` are `ReadableStream`s that end with the
+session. `write` takes a string or bytes and waits while the socket's buffer is full, so a writer in
+a loop keeps to the network's pace.
+
+Read or cancel both streams. Output nobody reads waits in memory, and past 8 MiB on one stream
+(`maxUnreadBytes`) the session ends with `OUTPUT_OVERFLOW`. Cancelling both streams ends the session
+and stops the command; so do `close()` and the `signal` option's abort.
+
+```ts
+const tail = await imp.openExec('dev', ['tail', '-f', '/var/log/app.log']);
+
+void tail.stderr.cancel();
+
+try {
+  for await (const chunk of tail.stdout) {
+    if (process.stdout.write(chunk) === false) {
+      break;
+    }
+  }
+} finally {
+  tail.close();
+}
+```
+
+`imp.openConsole` opens the root user's login shell with a tty, as `imp console` does. With
+[xterm.js](https://xtermjs.org):
+
+```ts
+const shell = await imp.openConsole('dev', { cols: term.cols, rows: term.rows });
+
+term.onData((data) => {
+  shell.write(data).catch(() => {});
+});
+term.onResize(({ cols, rows }) => shell.resize(cols, rows));
+
+const reader = shell.stdout.getReader();
+
+for (let read = await reader.read(); !read.done; read = await reader.read()) {
+  term.write(read.value);
+}
+```
+
+With `session: 'main'`, `openConsole` and `openExec` start that session, or attach to it if it runs,
+and the shell outlives the handle: `close()` detaches.
+`imp.openAttach('dev', 'main', { cols, rows })` attaches to a running session; its `stdout` starts
+with a replay of the recent output. `sessions.list` names them without waking the imp. `started`
+resolves with `{ pid, session, created }`. When impd ends the socket while the session runs on,
+`exit` rejects with `DETACHED`, and its `data.reason` says why: `taken_over` (another client
+attached; one is attached at a time), `slow` (the client fell too far behind) or `lost` (impd lost
+the guest, as when the imp slept; attach again).
+
+With a tty, `sendSignal('SIGINT')` and `sendSignal('SIGQUIT')` send ^C and ^\ as keys, so they reach
+the foreground job; other signals, and every signal without a tty, go to the process. A write after
+the session ended rejects with `CLOSED`.
+
+The socket authenticates with a single-use exec ticket from `exec.ticket`, so the token never goes
+in a URL; a browser behind a proxy that adds the token works the same way.
+
+`exit` resolves with `{ code, signal }`, where `code` is null when a signal ended the command. When
+the command did not run to its exit, `exit` rejects with an `ExecError` whose `code` is impd's (as
+in the table below, plus `EXEC_FAILED` when the command cannot start) or one of `UNAUTHORIZED` (also
+for an exec ticket that expired or was used), `UNREACHABLE`, `RESTARTING`, `CONNECTION_CLOSED`,
+`DETACHED`, `BAD_MESSAGE`, `CLOSED`, `OUTPUT_OVERFLOW` and `LOCAL_ERROR`. Its `data` is impd's error
+data.
+
+## Errors
+
+A failed call throws an `ORPCError`. impd's errors carry a `code` and typed `data`:
+
+| Code                  | When                                                 | `data`                                 |
+| --------------------- | ---------------------------------------------------- | -------------------------------------- |
+| `NOT_FOUND`           | No imp, image, checkpoint or session has that name.  | `{ kind, name }`                       |
+| `CONFLICT`            | The name is taken.                                   | `{ kind, name }`                       |
+| `INVALID_STATE`       | The imp's state does not allow the call.             | `{ state, allowed }`                   |
+| `RAM_BUDGET_EXCEEDED` | The host has no room, even after sleeping idle imps. | `{ budgetMib, usedMib, requestedMib }` |
+| `SERVICE_UNAVAILABLE` | impd is stopping.                                    |                                        |
+| `FORBIDDEN`           | An exec ticket was used for another imp.             |                                        |
+| `AGENT_OUTDATED`      | The imp's agent has no sessions; stop and start it.  |                                        |
+
+```ts
+import { isDefinedError, safe } from '@zgeoff/imp-client';
+
+const [error, created] = await safe(imp.imps.create({ name: 'dev' }));
+
+if (isDefinedError(error) && error.code === 'RAM_BUDGET_EXCEEDED') {
+  console.log(`needs ${error.data.requestedMib} MiB`);
+}
+```
+
+A 401 means the token is wrong.
+
+## Versions
+
+The client and impd are released together with the same version. `imp.checkServer()` tells whether
+impd speaks this client's API: the major version must match, and before 1.0 the minor version too.
+
+```ts
+const check = await imp.checkServer();
+
+if (!check.compatible) {
+  throw new Error(`impd ${check.serverVersion} does not match client ${check.clientVersion}`);
+}
+```