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 +3 -2
- package/llms.txt +7 -5
- package/package.json +1 -1
- package/proxy/dist/background.js +197 -0
- package/proxy/dist/capture.js +18 -2
- package/proxy/dist/cli.js +5 -0
- package/proxy/dist/command.js +9 -4
- package/proxy/dist/index.js +2 -0
- package/proxy/dist/pidfile.js +24 -0
- package/proxy/dist/ready.js +14 -0
- package/proxy/dist/stop.js +13 -28
- package/proxy/dist/upstreams.js +30 -19
- package/proxy/package.json +1 -1
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
|
-
-
|
|
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
|
|
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
|
@@ -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
|
+
}
|
package/proxy/dist/capture.js
CHANGED
|
@@ -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
|
-
|
|
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}: ${
|
|
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 {
|
package/proxy/dist/command.js
CHANGED
|
@@ -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
|
|
38
|
-
llmspy
|
|
39
|
-
|
|
40
|
-
llmspy
|
|
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):
|
package/proxy/dist/index.js
CHANGED
|
@@ -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);
|
package/proxy/dist/pidfile.js
CHANGED
|
@@ -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
|
+
}
|
package/proxy/dist/stop.js
CHANGED
|
@@ -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,
|
|
5
|
+
import { checkPidFile, PID_FILE, pingPid } from './pidfile.js';
|
|
6
6
|
const POLL_MS = 100;
|
|
7
7
|
const POLLS = 50;
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
15
|
+
let state;
|
|
23
16
|
try {
|
|
24
|
-
|
|
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 (
|
|
44
|
-
|
|
45
|
-
|
|
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
|
}
|
package/proxy/dist/upstreams.js
CHANGED
|
@@ -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
|
|
23
|
-
if (
|
|
24
|
-
throw new Error(`LLMSPY_UPSTREAMS:
|
|
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.
|