llmspy 0.4.0 → 0.6.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.
package/README.md CHANGED
@@ -110,7 +110,7 @@ With **Node.js 26 or later** (`node --version`), from any folder:
110
110
  npx llmspy
111
111
  ```
112
112
 
113
- This serves the proxy and the UI on `http://127.0.0.1:8080`, in the foreground. Stop it with Ctrl+C, or with `npx llmspy stop` from any terminal. To keep the `llmspy` command to hand, install it once with `npm install -g llmspy`; `llmspy --help` lists its commands and settings. `npx` runs the version it has cached, and `npx llmspy@latest` the newest.
113
+ This serves the proxy and the UI on `http://127.0.0.1:8080`, in the foreground. Stop it with Ctrl+C, or with `npx llmspy stop` from any terminal. To run it in the background instead, use `npx llmspy --background` (`-b`): it returns once LLMSpy is ready, its output goes to `~/.llmspy/llmspy.log`, and `npx llmspy stop` stops it. To keep the `llmspy` command to hand, install it once with `npm install -g llmspy`; `llmspy --help` lists its commands and settings. `npx` runs the version it has cached, and `npx llmspy@latest` the newest.
114
114
 
115
115
  With Docker, from a clone of the repo:
116
116
 
@@ -171,6 +171,7 @@ The `llmspy` command, from npm (`npx llmspy`, or `llmspy` once installed with `n
171
171
  | Command | What it does |
172
172
  | ------------------ | ------------------------------------------------------------------- |
173
173
  | `llmspy` | Start LLMSpy in the foreground |
174
+ | `llmspy -b` | Start LLMSpy in the background (`--background`) |
174
175
  | `llmspy stop` | Stop LLMSpy started with `llmspy` or `npm start`, from any terminal |
175
176
  | `llmspy --help` | List the commands and the settings |
176
177
  | `llmspy --version` | Print the version |
@@ -196,7 +197,7 @@ An upstream is an API that LLMSpy forwards to, reached through its own path pref
196
197
 
197
198
  ### Adding an upstream
198
199
 
199
- Set `LLMSPY_UPSTREAMS` to a comma-separated list of `name=url` before starting LLMSpy. Each entry adds the prefix `/<name>`, and a name that is already there is replaced. A path in the URL is kept and the rest of the request path is appended to it, so the app's base URL is LLMSpy's address plus the prefix:
200
+ Set `LLMSPY_UPSTREAMS` to a comma-separated list of `name=url` before starting LLMSpy. Each entry adds the prefix `/<name>`, and a name that is already there is replaced. Giving the same name twice is an error. A path in the URL is kept and the rest of the request path is appended to it, so the app's base URL is LLMSpy's address plus the prefix:
200
201
 
201
202
  ```
202
203
  LLMSPY_UPSTREAMS=openrouter=https://openrouter.ai/api/v1
package/llms.txt CHANGED
@@ -18,14 +18,16 @@ Running without Docker needs Node.js 26 or later (`engines` in `package.json`);
18
18
 
19
19
  | How | Start | Stop |
20
20
  |---|---|---|
21
- | npm package | `npx --yes llmspy` (or `llmspy`, after `npm install -g llmspy`) | `npx --yes llmspy stop` (`llmspy stop`), from any terminal |
21
+ | npm package, in the background (for agents and scripts) | `npx --yes llmspy --background` (or `llmspy --background`, after `npm install -g llmspy`) | `npx --yes llmspy stop` (`llmspy stop`), from any terminal |
22
+ | npm package, in the terminal | `npx --yes llmspy` (`llmspy`) | Ctrl+C, or `llmspy stop` from any terminal |
22
23
  | Docker (runs in the background, restarts with Docker) | `npm run start:docker` (`docker compose up -d --build`) | `npm run stop:docker` (`docker compose down`) |
23
24
  | Built, local | `npm run build`, then `npm start` | `npm run stop`, from any terminal |
24
25
  | Development, with reload | `npm run dev` (UI also on `http://localhost:3000`) | Ctrl+C in its terminal |
25
26
 
26
- - Ready when `GET http://127.0.0.1:8080/ping` answers `200`. `llmspy`, `npm start` and `npm run dev` stay in the foreground: run them in the background and poll `/ping`. Pass `--yes` to `npx`, or the first run waits for an answer to "Ok to proceed?" before installing the package, which blocks a run in the background.
27
+ - `llmspy --background` (`-b`) returns once LLMSpy is listening: it prints the same lines a foreground start does (the UI address and the base URLs), the pid, the log file and the command that stops it, and exits `0`. The background LLMSpy writes its output to `~/.llmspy/llmspy.log`; a start that succeeds moves the last log to `~/.llmspy/llmspy.log.old`, and one that fails leaves its output in `~/.llmspy/llmspy.log.new`. If an LLMSpy started with `llmspy`, `npm start` or `npm run dev` is already running (its pid file names a process that answers `/ping`), it says so and exits `0` without starting another. Anything else on the port, Docker's LLMSpy included, makes the start fail: if LLMSpy exits while starting (a port in use, a bad setting), or is not listening within 60 seconds (then it is stopped), it prints the end of the log and exits `1`.
28
+ - `llmspy` with no argument, `npm start` and `npm run dev` stay in the foreground; ready when `GET http://127.0.0.1:8080/ping` answers `200`. To run one of them from an agent, run it in the background and poll `/ping`. Pass `--yes` to `npx`, or the first run waits for an answer to "Ok to proceed?" before installing the package, which blocks a run in the background.
27
29
  - All of them use port 8080. Stop one before starting another; a second start on a taken port fails with `EADDRINUSE` and exits `1`.
28
- - `llmspy`, `npm start` and `npm run dev` write `~/.llmspy/llmspy.pid` (`{"pid", "url"}`) once they listen. `llmspy stop` (in a clone, `npm run stop` runs the same) stops that process only if `/ping` at that URL reports the same pid, so a stale or unreadable file is removed and nothing else is killed. It exits `0` when LLMSpy is stopped or was not running, and `1` when it did not stop within 5 seconds or the pid file could not be read. It does not stop Docker. For `npm run dev` it stops the proxy, but the watcher starts it again on the next file change: stop `npm run dev` with Ctrl+C.
30
+ - `llmspy` (also in the background), `npm start` and `npm run dev` write `~/.llmspy/llmspy.pid` (`{"pid", "url"}`) once they listen. `llmspy stop` (in a clone, `npm run stop` runs the same) stops that process only if `/ping` at that URL reports the same pid, so a stale or unreadable file is removed and nothing else is killed. It exits `0` when LLMSpy is stopped or was not running, and `1` when it did not stop within 5 seconds or the pid file could not be read. It does not stop Docker. For `npm run dev` it stops the proxy, but the watcher starts it again on the next file change: stop `npm run dev` with Ctrl+C.
29
31
  - `llmspy --help` lists the commands and settings, `llmspy --version` prints the version. Any other argument exits `1`; on Node.js older than 26 `llmspy` says so and exits `1`.
30
32
  - On start LLMSpy prints the database file and how long calls are kept (`Calls kept 7 days in …`), then the base URL of each upstream. A bad `LLMSPY_UPSTREAMS` or `LLMSPY_RETENTION_DAYS` prints the reason and exits `1`.
31
33
 
@@ -57,7 +59,7 @@ Environment variables, read once at startup:
57
59
 
58
60
  `LLMSPY_UPSTREAMS`:
59
61
 
60
- - Each entry adds the prefix `/<name>`. A name that is already there (`anthropic`, `openai`) is replaced.
62
+ - Each entry adds the prefix `/<name>`. A name that is already there (`anthropic`, `openai`) is replaced. A name given twice in `LLMSPY_UPSTREAMS` is refused, so two upstreams always need different names.
61
63
  - Names are lowercase letters, digits and dashes, starting with a letter or digit. `api`, `assets`, `events` and `ping` are refused.
62
64
  - URLs must be `http` or `https`. A path in the URL is kept and the request path is appended: `gw=https://gateway.example/v1` sends `/gw/messages` to `https://gateway.example/v1/messages`.
63
65
  - Set it in the shell, or in a settings file. For `llmspy` (the npm package) that file is `~/.llmspy/.env`: `LLMSPY_UPSTREAMS=llmock=http://127.0.0.1:8001 npx --yes llmspy` for one run, or a line `LLMSPY_UPSTREAMS=...` in `~/.llmspy/.env` to keep it. `llmspy` never reads a `.env` in the current folder: that is usually the app's own, with its API keys, so do not write LLMSpy settings there. The shell wins over the file; `llmspy` prints `Settings read from <file>` when the file exists, and exits `1` if it can not be read.
@@ -144,7 +146,7 @@ Only `2xx` responses are parsed. For a `4xx`/`5xx` call, `llm` has the request f
144
146
  | What the app gets | Why | In the record |
145
147
  |---|---|---|
146
148
  | `404 text/plain` `LLMSpy: no upstream for <path>. Known prefixes: …` | The first path segment is not an upstream | Nothing recorded |
147
- | `502 text/plain` `LLMSpy could not reach <origin>: …` | DNS, connection or TLS failure to the upstream | `error`, no `response` |
149
+ | `502 text/plain` `LLMSpy could not reach <origin>: …` | DNS, connection or TLS failure to the upstream. A refused connection adds `(nothing accepted the connection: is the server running, on that port?)`: usually a local upstream that is not started, or a wrong port | `error`, no `response` |
148
150
  | The connection is cut | The upstream's reply broke off part-way | `error`, `response` with what arrived |
149
151
  | The provider's own status and body | Anything the provider answered, `4xx`/`5xx` included | `response` as sent |
150
152
  | `403 text/plain` | A traffic endpoint called with another `Host` or `Origin` (above) | Nothing recorded |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "llmspy",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "description": "Local developer tool for intercepting and displaying LLM API traffic",
5
5
  "license": "MIT",
6
6
  "author": "piyook",
@@ -0,0 +1,197 @@
1
+ // `llmspy --background`: starts LLMSpy in the background and returns once it
2
+ // is listening. The background process is a plain `llmspy`, with its output in
3
+ // a log file; it loads ~/.llmspy/.env itself, so what it says about that is in
4
+ // the log too. It says it is listening with a message on an IPC channel
5
+ // (ready.ts), so readiness does not depend on the pid file, which LLMSpy may
6
+ // fail to write. `llmspy stop` stops it, as it would a foreground one.
7
+ import { spawn } from 'node:child_process';
8
+ import { closeSync, mkdirSync, openSync, readFileSync, renameSync, } from 'node:fs';
9
+ import { homedir } from 'node:os';
10
+ import * as path from 'node:path';
11
+ import { checkPidFile, PID_FILE } from './pidfile.js';
12
+ import { BACKGROUND_ENV, READY } from './ready.js';
13
+ /** The background LLMSpy's output. */
14
+ const LOG_FILE = path.join(homedir(), '.llmspy', 'llmspy.log');
15
+ /**
16
+ * A new run writes here, and the file becomes LOG_FILE (the last one moving
17
+ * to LOG_FILE.old) only once it is listening: a start that fails leaves the
18
+ * log of an LLMSpy that may still be running alone.
19
+ */
20
+ const NEW_LOG_FILE = `${LOG_FILE}.new`;
21
+ /** Generous: startup prunes and checks the database before it listens. */
22
+ const TIMEOUT_MS = 60_000;
23
+ /** How long a process that timed out gets to end once it is told to. */
24
+ const STOP_MS = 3000;
25
+ /** Lines of the log shown when the background LLMSpy did not start. */
26
+ const TAIL_LINES = 20;
27
+ /** The Node flags passed on to the background process: loaders, such as tsx's. */
28
+ const LOADER_FLAGS = new Set([
29
+ '--import',
30
+ '--require',
31
+ '-r',
32
+ '--loader',
33
+ '--experimental-loader',
34
+ ]);
35
+ /** Waits for `child` to say it is ready, to exit, to fail to start, or for `timeoutMs`. */
36
+ export function waitUntilReady(child, timeoutMs = TIMEOUT_MS) {
37
+ return new Promise((resolve) => {
38
+ const done = (outcome) => {
39
+ clearTimeout(timer);
40
+ child.off('message', onMessage);
41
+ child.off('exit', onExit);
42
+ child.off('error', onError);
43
+ resolve(outcome);
44
+ };
45
+ const onMessage = (message) => {
46
+ if (message?.type === READY)
47
+ done({ kind: 'ready' });
48
+ };
49
+ const onExit = () => done({ kind: 'exited' });
50
+ const onError = (error) => done({ kind: 'failed', error });
51
+ const timer = setTimeout(() => done({ kind: 'timeout' }), timeoutMs);
52
+ child.on('message', onMessage);
53
+ child.on('exit', onExit);
54
+ child.on('error', onError);
55
+ });
56
+ }
57
+ /** Resolves true once `child` has exited, false if it has not within `ms`. */
58
+ export function waitForExit(child, ms = STOP_MS) {
59
+ if (child.exitCode !== null || child.signalCode !== null)
60
+ return Promise.resolve(true);
61
+ return new Promise((resolve) => {
62
+ const onExit = () => {
63
+ clearTimeout(timer);
64
+ resolve(true);
65
+ };
66
+ const timer = setTimeout(() => {
67
+ child.off('exit', onExit);
68
+ resolve(false);
69
+ }, ms);
70
+ child.once('exit', onExit);
71
+ });
72
+ }
73
+ /** The loader flags in `execArgv` (`--import x` or `--import=x`), and nothing else, such as `--inspect`. */
74
+ export function loaderArgs(execArgv) {
75
+ const kept = [];
76
+ for (let i = 0; i < execArgv.length; i++) {
77
+ const arg = execArgv[i];
78
+ const [flag] = arg.split('=', 1);
79
+ if (!LOADER_FLAGS.has(flag))
80
+ continue;
81
+ if (arg.includes('='))
82
+ kept.push(arg);
83
+ else if (i + 1 < execArgv.length)
84
+ kept.push(arg, execArgv[++i]);
85
+ }
86
+ return kept;
87
+ }
88
+ /** The command that stops LLMSpy, as this one was run: npm sets npm_command for npx. */
89
+ export function stopCommand(env = process.env) {
90
+ return env.npm_command === 'exec' ? 'npx llmspy stop' : 'llmspy stop';
91
+ }
92
+ /** The new run's log becomes LOG_FILE; resolves with where its output now is. */
93
+ function keepNewLog() {
94
+ try {
95
+ renameSync(LOG_FILE, `${LOG_FILE}.old`);
96
+ }
97
+ catch {
98
+ // No log yet, or it can't be moved: the new one replaces it below.
99
+ }
100
+ try {
101
+ renameSync(NEW_LOG_FILE, LOG_FILE);
102
+ return LOG_FILE;
103
+ }
104
+ catch {
105
+ return NEW_LOG_FILE;
106
+ }
107
+ }
108
+ function readLog(file) {
109
+ try {
110
+ return readFileSync(file, 'utf8');
111
+ }
112
+ catch {
113
+ return '';
114
+ }
115
+ }
116
+ /** Starts LLMSpy in the background, and resolves with the exit code. */
117
+ export async function startInBackground() {
118
+ let state;
119
+ try {
120
+ state = await checkPidFile();
121
+ }
122
+ catch (error) {
123
+ console.error(`Could not read ${PID_FILE}: ${error.message}`);
124
+ return 1;
125
+ }
126
+ if (state.kind === 'running') {
127
+ console.log(`LLMSpy is already running at ${state.url} (pid ${state.pid}).`);
128
+ return 0;
129
+ }
130
+ const { outcome, pid } = await launch();
131
+ if (outcome.kind === 'ready') {
132
+ const log = keepNewLog();
133
+ process.stdout.write(readLog(log));
134
+ console.log(`\nRunning in the background (pid ${pid}). Log: ${log}\nStop it with: ${stopCommand()}`);
135
+ return 0;
136
+ }
137
+ return reportFailure(outcome, pid);
138
+ }
139
+ /** Starts a plain `llmspy` detached, its output in NEW_LOG_FILE, and waits for it. */
140
+ async function launch() {
141
+ mkdirSync(path.dirname(LOG_FILE), { recursive: true });
142
+ const log = openSync(NEW_LOG_FILE, 'w');
143
+ let child;
144
+ try {
145
+ child = spawn(process.execPath, [...loaderArgs(process.execArgv), process.argv[1]], {
146
+ detached: true,
147
+ stdio: ['ignore', log, log, 'ipc'],
148
+ windowsHide: true,
149
+ env: { ...process.env, [BACKGROUND_ENV]: '1' },
150
+ });
151
+ }
152
+ finally {
153
+ closeSync(log);
154
+ }
155
+ // Kept for the whole launch: a kill or disconnect that fails after the
156
+ // wait must not crash the launcher.
157
+ child.on('error', () => { });
158
+ const waited = await waitUntilReady(child);
159
+ let outcome;
160
+ if (waited.kind === 'timeout') {
161
+ child.kill();
162
+ outcome = { kind: 'timeout', stopped: await waitForExit(child) };
163
+ }
164
+ else {
165
+ outcome = waited;
166
+ }
167
+ if (child.connected)
168
+ child.disconnect();
169
+ child.unref();
170
+ return { outcome, pid: child.pid };
171
+ }
172
+ /** Why the background LLMSpy (`pid`) did not start. */
173
+ export function failureMessage(outcome, pid) {
174
+ const within = `LLMSpy did not start within ${TIMEOUT_MS / 1000} s`;
175
+ switch (outcome.kind) {
176
+ case 'failed':
177
+ return `Could not start LLMSpy: ${outcome.error.message}`;
178
+ case 'timeout':
179
+ return outcome.stopped
180
+ ? `${within}, so it was stopped.`
181
+ : `${within} and may still be running (pid ${pid}).`;
182
+ case 'exited':
183
+ return 'LLMSpy did not start.';
184
+ }
185
+ }
186
+ /** The last `count` lines of `text`, without its trailing newline. */
187
+ export function lastLines(text, count = TAIL_LINES) {
188
+ return text.trimEnd().split('\n').slice(-count).join('\n');
189
+ }
190
+ /** Says why the background LLMSpy did not start, with the end of its log, and returns the exit code. */
191
+ function reportFailure(outcome, pid) {
192
+ console.error(failureMessage(outcome, pid));
193
+ const tail = lastLines(readLog(NEW_LOG_FILE));
194
+ if (tail)
195
+ console.error(`From ${NEW_LOG_FILE}:\n${tail}`);
196
+ return 1;
197
+ }
@@ -113,6 +113,21 @@ export function isLiveStream(headers) {
113
113
  return (isEventStream(headers['content-type']) &&
114
114
  (encoding === '' || encoding === 'identity'));
115
115
  }
116
+ /**
117
+ * Why a request never reached the upstream, as told to the app and stored.
118
+ * A host with several addresses (`localhost`: ::1 and 127.0.0.1) fails with
119
+ * an AggregateError whose own message is empty, so its parts are used.
120
+ * A refused connection most often means a local server that is not started.
121
+ */
122
+ export function failureReason(error) {
123
+ const parts = (error.errors ?? [])
124
+ .map((part) => (part instanceof Error ? part.message : ''))
125
+ .filter(Boolean);
126
+ const reason = error.message || parts.join(', ') || error.code || 'unknown error';
127
+ return error.code === 'ECONNREFUSED'
128
+ ? `${reason} (nothing accepted the connection: is the server running, on that port?)`
129
+ : reason;
130
+ }
116
131
  /**
117
132
  * Forwards one request to `target` and streams the response back unchanged,
118
133
  * chunk by chunk, keeping a copy of both bodies. Each handler gets the same
@@ -211,13 +226,14 @@ export function forwardAndCapture(req, res, { project, provider, target }, { onU
211
226
  response.pipe(res);
212
227
  });
213
228
  upstreamReq.on('error', (error) => {
214
- finish(`Upstream request failed: ${error.message}`);
229
+ const reason = failureReason(error);
230
+ finish(`Upstream request failed: ${reason}`);
215
231
  if (res.headersSent) {
216
232
  res.destroy();
217
233
  }
218
234
  else {
219
235
  res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
220
- res.end(`LLMSpy could not reach ${target.origin}: ${error.message}`);
236
+ res.end(`LLMSpy could not reach ${target.origin}: ${reason}`);
221
237
  }
222
238
  });
223
239
  res.on('finish', () => finish());
package/proxy/dist/cli.js CHANGED
@@ -11,6 +11,11 @@ if (tooOld) {
11
11
  }
12
12
  const args = process.argv.slice(2);
13
13
  switch (parseCommand(args)) {
14
+ case 'background': {
15
+ const { startInBackground } = await import('./background.js');
16
+ process.exitCode = await startInBackground();
17
+ break;
18
+ }
14
19
  case 'start': {
15
20
  const { ENV_FILE, loadEnvFile } = await import('./envfile.js');
16
21
  try {
@@ -10,6 +10,9 @@ export function parseCommand(args) {
10
10
  if (args.length > 1)
11
11
  return undefined;
12
12
  switch (args[0]) {
13
+ case '--background':
14
+ case '-b':
15
+ return 'background';
13
16
  case 'stop':
14
17
  return 'stop';
15
18
  case 'help':
@@ -34,10 +37,12 @@ export function helpText(version) {
34
37
  return `LLMSpy ${version}: shows LLM API traffic live, in a web UI on your machine.
35
38
 
36
39
  Usage:
37
- llmspy start LLMSpy in the foreground (Ctrl+C stops it)
38
- llmspy stop stop the LLMSpy running on this machine
39
- llmspy --version print the version
40
- llmspy --help show this
40
+ llmspy start LLMSpy in this terminal (Ctrl+C stops it)
41
+ llmspy --background start it in the background instead, with its output in
42
+ ~/.llmspy/llmspy.log; also -b
43
+ llmspy stop stop the LLMSpy running on this machine
44
+ llmspy --version print the version
45
+ llmspy --help show this
41
46
 
42
47
  Settings are environment variables, set in the shell or in ~/.llmspy/.env
43
48
  (the shell wins):
@@ -4,6 +4,7 @@ import * as path from 'node:path';
4
4
  import { hostForUrl } from './guard.js';
5
5
  import { writePidFile } from './pidfile.js';
6
6
  import { ProxyServer } from './proxy.js';
7
+ import { notifyReady } from './ready.js';
7
8
  import { parseRetentionDays, RequestStore } from './store.js';
8
9
  import { parseUpstreams } from './upstreams.js';
9
10
  import { readVersion } from './version.js';
@@ -78,6 +79,7 @@ async function start() {
78
79
  console.log('\nFor example:');
79
80
  console.log(` ANTHROPIC_BASE_URL=${base}/anthropic`);
80
81
  console.log(` OPENAI_BASE_URL=${base}/openai/v1`);
82
+ notifyReady();
81
83
  }
82
84
  catch (error) {
83
85
  console.error('Failed to start LLMSpy:', error);
@@ -44,6 +44,30 @@ export function readPidFile(file = PID_FILE) {
44
44
  return 'invalid';
45
45
  }
46
46
  }
47
+ /** The pid that LLMSpy at `url` answers `/ping` with, or undefined if nothing does. */
48
+ export async function pingPid(url) {
49
+ try {
50
+ const res = await fetch(`${url}/ping`, {
51
+ signal: AbortSignal.timeout(2000),
52
+ });
53
+ return (await res.json()).pid;
54
+ }
55
+ catch {
56
+ return undefined;
57
+ }
58
+ }
59
+ /**
60
+ * What `file` says, checked against `/ping` at its URL: `running` only when
61
+ * LLMSpy there answers with the recorded pid, `stale` when nothing does or
62
+ * another process does. Read errors other than a missing file are thrown.
63
+ */
64
+ export async function checkPidFile(file = PID_FILE) {
65
+ const record = readPidFile(file);
66
+ if (typeof record !== 'object')
67
+ return { kind: record };
68
+ const answer = await pingPid(record.url);
69
+ return { kind: answer === record.pid ? 'running' : 'stale', ...record };
70
+ }
47
71
  /** Removes the file only if it is still this process's, so a newer LLMSpy's record is left alone. */
48
72
  export function removePidFile(file = PID_FILE) {
49
73
  try {
@@ -0,0 +1,14 @@
1
+ // Between `llmspy --background` (background.ts) and the LLMSpy it starts: the
2
+ // background process says it is listening with one message on the IPC channel.
3
+ // Kept apart from background.ts so the server does not load the launcher.
4
+ /** Set for the background process, which then reports on the IPC channel. */
5
+ export const BACKGROUND_ENV = 'LLMSPY_BACKGROUND';
6
+ export const READY = 'llmspy:ready';
7
+ /** Run by LLMSpy once it listens: tells `llmspy --background` it is ready. */
8
+ export function notifyReady() {
9
+ if (process.env[BACKGROUND_ENV] !== '1' || !process.connected)
10
+ return;
11
+ // The launcher may have gone (Ctrl+C, a command timeout): with a callback,
12
+ // a send that fails is ignored rather than crashing LLMSpy.
13
+ process.send?.({ type: READY }, undefined, undefined, () => { });
14
+ }
@@ -2,49 +2,34 @@
2
2
  // `npm start` or `npm run dev` on this machine, found from the pid file it
3
3
  // writes on startup. Not for Docker (use `npm run stop:docker`).
4
4
  import { rmSync } from 'node:fs';
5
- import { PID_FILE, readPidFile } from './pidfile.js';
5
+ import { checkPidFile, PID_FILE, pingPid } from './pidfile.js';
6
6
  const POLL_MS = 100;
7
7
  const POLLS = 50;
8
- /** The pid that answers at `url`, or undefined if nothing does. */
9
- async function pingPid(url) {
10
- try {
11
- const res = await fetch(`${url}/ping`, {
12
- signal: AbortSignal.timeout(2000),
13
- });
14
- return (await res.json()).pid;
15
- }
16
- catch {
17
- return undefined;
18
- }
19
- }
8
+ const NOT_RUNNING = {
9
+ none: 'no pid file',
10
+ invalid: 'removed an unreadable pid file',
11
+ stale: 'removed a stale pid file',
12
+ };
20
13
  /** Stops the LLMSpy recorded in `file`, and resolves with the exit code. */
21
14
  export async function stop(file = PID_FILE) {
22
- let record;
15
+ let state;
23
16
  try {
24
- record = readPidFile(file);
17
+ state = await checkPidFile(file);
25
18
  }
26
19
  catch (error) {
27
20
  console.error(`Could not read ${file}: ${error.message}`);
28
21
  return 1;
29
22
  }
30
- if (record === 'none') {
31
- console.log('LLMSpy is not running (no pid file).');
32
- return 0;
33
- }
34
- if (record === 'invalid') {
35
- rmSync(file, { force: true });
36
- console.log('LLMSpy is not running (removed an unreadable pid file).');
37
- return 0;
38
- }
39
- const { pid, url } = record;
40
23
  // A pid file left by a process that died without cleaning up may name a
41
24
  // pid the system has since given to something else: only stop it if
42
25
  // LLMSpy at the recorded URL says it is that process.
43
- if ((await pingPid(url)) !== pid) {
44
- rmSync(file, { force: true });
45
- console.log('LLMSpy is not running (removed a stale pid file).');
26
+ if (state.kind !== 'running') {
27
+ if (state.kind !== 'none')
28
+ rmSync(file, { force: true });
29
+ console.log(`LLMSpy is not running (${NOT_RUNNING[state.kind]}).`);
46
30
  return 0;
47
31
  }
32
+ const { pid, url } = state;
48
33
  try {
49
34
  process.kill(pid, 'SIGTERM');
50
35
  }
@@ -8,40 +8,51 @@ const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
8
8
  /**
9
9
  * Builds the upstream map from the defaults plus `LLMSPY_UPSTREAMS`,
10
10
  * a comma-separated list of `name=url` (e.g. `ollama=http://localhost:11434`).
11
- * A name that matches a default replaces it.
11
+ * A name that matches a default replaces it; a name given twice is an error,
12
+ * since only one of the two could be kept.
12
13
  */
13
14
  export function parseUpstreams(spec) {
14
15
  const upstreams = new Map();
15
16
  for (const [name, url] of Object.entries(DEFAULT_UPSTREAMS)) {
16
17
  upstreams.set(name, new URL(url));
17
18
  }
19
+ const given = new Set();
18
20
  for (const entry of (spec ?? '').split(',')) {
19
21
  const trimmed = entry.trim();
20
22
  if (!trimmed)
21
23
  continue;
22
- const eq = trimmed.indexOf('=');
23
- if (eq < 1) {
24
- throw new Error(`LLMSPY_UPSTREAMS: expected name=url, got "${trimmed}"`);
25
- }
26
- const name = trimmed.slice(0, eq).trim().toLowerCase();
27
- const rawUrl = trimmed.slice(eq + 1).trim();
28
- if (!NAME_PATTERN.test(name) || RESERVED_NAMES.has(name)) {
29
- throw new Error(`LLMSPY_UPSTREAMS: "${name}" is not a usable name (lowercase letters, digits and dashes; not ${[...RESERVED_NAMES].join(', ')})`);
30
- }
31
- let url;
32
- try {
33
- url = new URL(rawUrl);
34
- }
35
- catch {
36
- throw new Error(`LLMSPY_UPSTREAMS: "${rawUrl}" for ${name} is not a valid URL`);
37
- }
38
- if (url.protocol !== 'http:' && url.protocol !== 'https:') {
39
- throw new Error(`LLMSPY_UPSTREAMS: ${name} must use http or https, got ${url.protocol}`);
24
+ const [name, url] = parseEntry(trimmed);
25
+ if (given.has(name)) {
26
+ throw new Error(`LLMSPY_UPSTREAMS: "${name}" is given more than once; each upstream needs its own name`);
40
27
  }
28
+ given.add(name);
41
29
  upstreams.set(name, url);
42
30
  }
43
31
  return upstreams;
44
32
  }
33
+ /** One trimmed `name=url` entry of `LLMSPY_UPSTREAMS`, checked. */
34
+ function parseEntry(entry) {
35
+ const eq = entry.indexOf('=');
36
+ if (eq < 1) {
37
+ throw new Error(`LLMSPY_UPSTREAMS: expected name=url, got "${entry}"`);
38
+ }
39
+ const name = entry.slice(0, eq).trim().toLowerCase();
40
+ const rawUrl = entry.slice(eq + 1).trim();
41
+ if (!NAME_PATTERN.test(name) || RESERVED_NAMES.has(name)) {
42
+ throw new Error(`LLMSPY_UPSTREAMS: "${name}" is not a usable name (lowercase letters, digits and dashes; not ${[...RESERVED_NAMES].join(', ')})`);
43
+ }
44
+ let url;
45
+ try {
46
+ url = new URL(rawUrl);
47
+ }
48
+ catch {
49
+ throw new Error(`LLMSPY_UPSTREAMS: "${rawUrl}" for ${name} is not a valid URL`);
50
+ }
51
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {
52
+ throw new Error(`LLMSPY_UPSTREAMS: ${name} must use http or https, got ${url.protocol}`);
53
+ }
54
+ return [name, url];
55
+ }
45
56
  /**
46
57
  * The upstreams as shown to the UI, in configuration order. Any user name
47
58
  * or password in a target URL is left out, so it never reaches a browser.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "llmspy-proxy",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "private": true,
5
5
  "type": "module"
6
6
  }