llmspy 0.5.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
@@ -197,7 +197,7 @@ An upstream is an API that LLMSpy forwards to, reached through its own path pref
197
197
 
198
198
  ### Adding an upstream
199
199
 
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. 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:
201
201
 
202
202
  ```
203
203
  LLMSPY_UPSTREAMS=openrouter=https://openrouter.ai/api/v1
package/llms.txt CHANGED
@@ -59,7 +59,7 @@ Environment variables, read once at startup:
59
59
 
60
60
  `LLMSPY_UPSTREAMS`:
61
61
 
62
- - 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.
63
63
  - Names are lowercase letters, digits and dashes, starting with a letter or digit. `api`, `assets`, `events` and `ping` are refused.
64
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`.
65
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.
@@ -146,7 +146,7 @@ Only `2xx` responses are parsed. For a `4xx`/`5xx` call, `llm` has the request f
146
146
  | What the app gets | Why | In the record |
147
147
  |---|---|---|
148
148
  | `404 text/plain` `LLMSpy: no upstream for <path>. Known prefixes: …` | The first path segment is not an upstream | Nothing recorded |
149
- | `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` |
150
150
  | The connection is cut | The upstream's reply broke off part-way | `error`, `response` with what arrived |
151
151
  | The provider's own status and body | Anything the provider answered, `4xx`/`5xx` included | `response` as sent |
152
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.5.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",
@@ -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());
@@ -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.5.0",
3
+ "version": "0.6.0",
4
4
  "private": true,
5
5
  "type": "module"
6
6
  }