viafrei 0.0.2 → 0.0.9

package/dist/failure.js

@@ -0,0 +1,186 @@
+import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { EXIT } from './config.js';
+const STATUS_TEXT = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    406: 'Not Acceptable',
+    408: 'Request Timeout',
+    410: 'Gone',
+    413: 'Payload Too Large',
+    415: 'Unsupported Media Type',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout'
+};
+const SYSCALL_TEXT = {
+    ECONNREFUSED: 'connection refused',
+    ENOTFOUND: 'host not found (DNS)',
+    EAI_AGAIN: 'DNS lookup failed',
+    ECONNRESET: 'connection reset by peer',
+    EHOSTUNREACH: 'host unreachable',
+    ENETUNREACH: 'network unreachable',
+    ETIMEDOUT: 'connection timed out',
+    EPIPE: 'connection closed while writing',
+    CERT_HAS_EXPIRED: 'the TLS certificate has expired',
+    UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'the TLS certificate could not be verified',
+    DEPTH_ZERO_SELF_SIGNED_CERT: 'the TLS certificate is self-signed'
+};
+/** Collapse anything to a single readable line. */
+function oneLine(text, limit = 200) {
+    const flattened = text.replace(/\s+/gu, ' ').trim();
+    return flattened.length > limit ? `${flattened.slice(0, limit - 1)}…` : flattened;
+}
+function errorCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current !== null && typeof current === 'object'; depth += 1) {
+        const code = current.code;
+        if (typeof code === 'string') {
+            return code;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
+/** True when the failure is worth exactly one more attempt. */
+export function isRetryable(error) {
+    if (error instanceof StreamableHTTPError) {
+        return error.code === 502 || error.code === 503 || error.code === 504;
+    }
+    const code = errorCode(error);
+    if (code === undefined) {
+        return false;
+    }
+    return ['ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT'].includes(code);
+}
+/** Raised by the fetch wrapper when our own timeout fired. */
+export class RequestTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`no answer within ${timeoutMs} ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'RequestTimeoutError';
+    }
+}
+/**
+ * How many same-origin hops are a redirect, and how many are a loop.
+ *
+ * Defined here, next to the sentence that quotes it, and imported by the fetch
+ * wrapper that enforces it. It used to be defined in `src/fetch.ts` and typed
+ * out again as a literal in `redirectLine()`, which is a number in two places
+ * and therefore a number that can disagree with itself.
+ */
+export const MAX_REDIRECTS = 5;
+/**
+ * Raised by the fetch wrapper when a redirect was not followed.
+ *
+ * Every request carries the caller's `--header` values. A redirect is the
+ * server choosing where those go next, so the choice is made here instead: one
+ * origin is one trust boundary, and crossing it is refused out loud rather than
+ * followed quietly.
+ */
+export class RedirectRefusedError extends Error {
+    reason;
+    from;
+    to;
+    httpStatus;
+    constructor(detail) {
+        super(`redirect not followed (${detail.reason})`);
+        this.name = 'RedirectRefusedError';
+        this.reason = detail.reason;
+        this.from = detail.from;
+        this.to = detail.to;
+        this.httpStatus = detail.status;
+    }
+}
+/**
+ * Turn any thrown value into one line plus an exit code.
+ *
+ * Three outcomes, and the distinction is the point: the endpoint answered and
+ * said no (REFUSED), the endpoint never answered (UNREACHABLE), or something
+ * else entirely (UNEXPECTED).
+ */
+export function describeFailure(error, url) {
+    if (error instanceof RedirectRefusedError) {
+        return { line: redirectLine(error), exitCode: EXIT.REFUSED };
+    }
+    if (error instanceof StreamableHTTPError && error.code !== undefined && error.code < 0) {
+        // The SDK uses a negative code for "the endpoint answered, but not with
+        // MCP" - a login page, an HTML error, a proxy's own 200. There is no
+        // HTTP status here, so printing one (`HTTP -1 HTTP error`) invented a
+        // fact, and "refused" was wrong twice over: it answered, and it did not
+        // refuse.
+        return {
+            line: `viafrei: ${url} answered, but not with MCP - ${oneLine(stripSdkPrefix(error.message), 120)}. Is that the Streamable-HTTP endpoint (usually .../mcp), or is something in front of it answering instead?`,
+            exitCode: EXIT.REFUSED
+        };
+    }
+    if (error instanceof StreamableHTTPError && error.code !== undefined) {
+        const status = error.code;
+        const name = STATUS_TEXT[status] ?? 'HTTP error';
+        const detail = extractServerDetail(error.message);
+        const suffix = detail === undefined ? '' : ` - ${detail}`;
+        return {
+            line: `viafrei: ${url} refused the request: HTTP ${status} ${name}${suffix}`,
+            exitCode: EXIT.REFUSED,
+            status
+        };
+    }
+    if (error instanceof RequestTimeoutError) {
+        return {
+            line: `viafrei: ${url} did not answer within ${error.timeoutMs} ms - the endpoint may be down, or --timeout is too short`,
+            exitCode: EXIT.UNREACHABLE
+        };
+    }
+    const code = errorCode(error);
+    if (code !== undefined) {
+        const explanation = SYSCALL_TEXT[code] ?? code;
+        return {
+            line: `viafrei: cannot reach ${url}: ${explanation} (${code}) - check your network connection; --url only if you relay through a proxy`,
+            exitCode: EXIT.UNREACHABLE
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (/fetch failed|network|socket/iu.test(message)) {
+        return {
+            line: `viafrei: cannot reach ${url}: ${oneLine(message)}`,
+            exitCode: EXIT.UNREACHABLE
+        };
+    }
+    return {
+        line: `viafrei: ${url}: ${oneLine(message)}`,
+        exitCode: EXIT.UNEXPECTED
+    };
+}
+/**
+ * The SDK wraps the response body into the error message. Keep a short, single
+ * line of it - it is often the only thing that says *why* - and drop the rest.
+ */
+function extractServerDetail(message) {
+    const marker = 'Error POSTing to endpoint:';
+    const index = message.indexOf(marker);
+    const body = index === -1 ? message : message.slice(index + marker.length);
+    const trimmed = oneLine(body, 120);
+    if (trimmed === '' || trimmed === 'null' || trimmed === 'undefined') {
+        return undefined;
+    }
+    return trimmed;
+}
+/** One line for a redirect we chose not to follow, naming both ends. */
+function redirectLine(error) {
+    if (error.reason === 'cross-origin') {
+        return `viafrei: ${error.from} answered HTTP ${error.httpStatus} redirecting to ${error.to} - a different origin, and this request carries the headers you gave me, so I did not follow it. Point --url at the final endpoint if that redirect is expected.`;
+    }
+    if (error.reason === 'too-many') {
+        return `viafrei: ${error.from} kept redirecting (more than ${MAX_REDIRECTS} hops, last ${error.to}) - that is a loop, not an endpoint.`;
+    }
+    return `viafrei: ${error.from} answered HTTP ${error.httpStatus} - a redirect with no Location to follow.`;
+}
+/** The SDK prefixes its own message; the user does not need our plumbing. */
+function stripSdkPrefix(message) {
+    return message.replace(/^Streamable HTTP error:\s*/u, '');
+}

package/dist/fetch.d.ts

@@ -0,0 +1,24 @@
+import type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
+/**
+ * `fetch` with a timeout, exactly one retry, and an explicit redirect policy.
+ *
+ * Three deliberate decisions, all because getting them wrong is worse than the
+ * feature:
+ *
+ * - **The event stream is never timed out.** The standalone `GET` is a
+ *   long-lived stream by design; a 30-second deadline on it would look like a
+ *   flaky server every 30 seconds.
+ * - **A timeout is not retried.** One retry after a timeout doubles the worst
+ *   case and hides a slow endpoint behind a longer wait. Retry covers the
+ *   momentary failures (a reset socket, a 503 from a proxy in front of the
+ *   server), not a server that is simply not answering.
+ * - **Redirects are followed by hand, and only within one origin.** Every
+ *   request here carries whatever `--header` the user gave us, which is how an
+ *   API key gets to the server. `redirect: 'follow'` would hand those headers
+ *   to whatever the `Location` says - `fetch` drops `Authorization` across
+ *   origins, but it does not drop `X-Api-Key`, and a server that can answer a
+ *   redirect can choose the origin. So the redirect is resolved here: same
+ *   origin is followed with the headers, a different origin is refused with one
+ *   line naming both. Nobody's key travels somewhere they did not point it.
+ */
+export declare function createFetch(timeoutMs: number): FetchLike;

package/dist/fetch.js

@@ -0,0 +1,120 @@
+import { MAX_REDIRECTS, RedirectRefusedError, RequestTimeoutError, isRetryable } from './failure.js';
+/** Statuses that mean "the hop in front of the server had a moment". */
+const RETRY_STATUS = new Set([502, 503, 504]);
+/** How long to wait before the single retry. */
+const RETRY_DELAY_MS = 250;
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const originOf = (url) => new URL(url).origin;
+/**
+ * `fetch` with a timeout, exactly one retry, and an explicit redirect policy.
+ *
+ * Three deliberate decisions, all because getting them wrong is worse than the
+ * feature:
+ *
+ * - **The event stream is never timed out.** The standalone `GET` is a
+ *   long-lived stream by design; a 30-second deadline on it would look like a
+ *   flaky server every 30 seconds.
+ * - **A timeout is not retried.** One retry after a timeout doubles the worst
+ *   case and hides a slow endpoint behind a longer wait. Retry covers the
+ *   momentary failures (a reset socket, a 503 from a proxy in front of the
+ *   server), not a server that is simply not answering.
+ * - **Redirects are followed by hand, and only within one origin.** Every
+ *   request here carries whatever `--header` the user gave us, which is how an
+ *   API key gets to the server. `redirect: 'follow'` would hand those headers
+ *   to whatever the `Location` says - `fetch` drops `Authorization` across
+ *   origins, but it does not drop `X-Api-Key`, and a server that can answer a
+ *   redirect can choose the origin. So the redirect is resolved here: same
+ *   origin is followed with the headers, a different origin is refused with one
+ *   line naming both. Nobody's key travels somewhere they did not point it.
+ */
+export function createFetch(timeoutMs) {
+    return async (url, init) => {
+        const method = (init?.method ?? 'GET').toUpperCase();
+        const isEventStream = method === 'GET';
+        /** One request, no redirect handling, with our timeout attached. */
+        const once = async (target, requestInit) => {
+            const withPolicy = { ...requestInit, redirect: 'manual' };
+            if (isEventStream) {
+                return fetch(target, withPolicy);
+            }
+            const timeout = AbortSignal.timeout(timeoutMs);
+            const signals = [timeout];
+            if (requestInit?.signal) {
+                signals.push(requestInit.signal);
+            }
+            try {
+                return await fetch(target, { ...withPolicy, signal: AbortSignal.any(signals) });
+            }
+            catch (error) {
+                if (timeout.aborted && requestInit?.signal?.aborted !== true) {
+                    throw new RequestTimeoutError(timeoutMs);
+                }
+                throw error;
+            }
+        };
+        /** One request plus any same-origin redirects it asks for. */
+        const attempt = async () => {
+            let target = String(url);
+            let requestInit = init;
+            for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+                const response = await once(target, requestInit);
+                if (!REDIRECT_STATUS.has(response.status)) {
+                    return response;
+                }
+                const location = response.headers.get('location');
+                await response.body?.cancel().catch(() => undefined);
+                if (location === null || location.trim() === '') {
+                    throw new RedirectRefusedError({
+                        reason: 'no-location',
+                        from: target,
+                        to: '(none)',
+                        status: response.status
+                    });
+                }
+                const next = new URL(location, target);
+                if (next.origin !== originOf(target)) {
+                    throw new RedirectRefusedError({
+                        reason: 'cross-origin',
+                        from: target,
+                        to: next.origin,
+                        status: response.status
+                    });
+                }
+                // Same origin: the headers are already meant for this server, so
+                // following is safe. 303 (and the historical 301/302 on a POST)
+                // means "ask again with GET, without the body".
+                const dropsBody = response.status === 303 || ((response.status === 301 || response.status === 302) && method !== 'GET');
+                if (dropsBody) {
+                    const { body: _body, ...rest } = requestInit ?? {};
+                    requestInit = { ...rest, method: 'GET' };
+                }
+                target = next.toString();
+            }
+            throw new RedirectRefusedError({
+                reason: 'too-many',
+                from: String(url),
+                to: target,
+                status: 0
+            });
+        };
+        const canRetry = () => !isEventStream && init?.signal?.aborted !== true;
+        let response;
+        try {
+            response = await attempt();
+        }
+        catch (error) {
+            if (canRetry() && isRetryable(error)) {
+                await sleep(RETRY_DELAY_MS);
+                return attempt();
+            }
+            throw error;
+        }
+        if (canRetry() && RETRY_STATUS.has(response.status)) {
+            await response.body?.cancel().catch(() => undefined);
+            await sleep(RETRY_DELAY_MS);
+            return attempt();
+        }
+        return response;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Programmatic entry point.
+ *
+ * The bridge is a command-line tool first (`npx viafrei`), but a client that
+ * wants to embed the relay - a desktop app shipping its own supervisor, say -
+ * should not have to spawn a process to do it.
+ */
+export { startBridge, type BridgeHandle, type BridgeHooks } from './bridge.js';
+export { DEFAULT_MCP_ORIGIN, DEFAULT_MCP_PATH, DEFAULT_MCP_URL, DEFAULT_TIMEOUT_MS, EXIT, TIMEOUT_ENV_VAR, URL_ENV_VAR, UsageError, helpText, parseOptions, type ExitCode, type Options } from './config.js';
+export { describeFailure, RequestTimeoutError, type Failure } from './failure.js';
+export { packageVersion } from './version.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Programmatic entry point.
+ *
+ * The bridge is a command-line tool first (`npx viafrei`), but a client that
+ * wants to embed the relay - a desktop app shipping its own supervisor, say -
+ * should not have to spawn a process to do it.
+ */
+export { startBridge } from './bridge.js';
+export { DEFAULT_MCP_ORIGIN, DEFAULT_MCP_PATH, DEFAULT_MCP_URL, DEFAULT_TIMEOUT_MS, EXIT, TIMEOUT_ENV_VAR, URL_ENV_VAR, UsageError, helpText, parseOptions } from './config.js';
+export { describeFailure, RequestTimeoutError } from './failure.js';
+export { packageVersion } from './version.js';

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The version printed by `--version`, read from the package manifest that ships
+ * beside `dist/`. One number, one source: no constant to forget to bump.
+ */
+export declare function packageVersion(): string;

package/dist/version.js

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+/**
+ * The version printed by `--version`, read from the package manifest that ships
+ * beside `dist/`. One number, one source: no constant to forget to bump.
+ */
+export function packageVersion() {
+    for (const relative of ['../package.json', '../../package.json']) {
+        try {
+            const raw = readFileSync(new URL(relative, import.meta.url), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === 'object') {
+                const { name, version } = parsed;
+                if (name === 'viafrei' && typeof version === 'string') {
+                    return version;
+                }
+            }
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return '0.0.0-unknown';
+}

package/package.json

@@ -1,8 +1,67 @@
 {
   "name": "viafrei",
-  "version": "0.0.2",
-  "description": "Reserved package name.",
-  "license": "MIT",
-  "main": "index.js",
-  "files": ["index.js", "README.md"]
+  "version": "0.0.9",
+  "description": "stdio<->Streamable-HTTP bridge for the ViaFrei MCP server - German road, rail, parking, charging and fuel data for stdio-only MCP clients",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "stdio",
+    "bridge",
+    "proxy",
+    "germany",
+    "transport",
+    "open-data"
+  ],
+  "homepage": "https://viafrei.de",
+  "bugs": "https://github.com/mavrovde/viafrei-bridge/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mavrovde/viafrei-bridge.git"
+  },
+  "license": "Apache-2.0",
+  "author": "ViaFrei",
+  "type": "module",
+  "bin": {
+    "viafrei": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "SOURCES.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true});require('node:fs').rmSync('.test-build',{recursive:true,force:true})\"",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test --test-timeout=30000 .test-build/test/*.test.js",
+    "test:gate": "node scripts/check-tarball.test.mjs",
+    "test:leaks": "node scripts/check-leaks.test.mjs",
+    "check:tarball": "node scripts/check-tarball.mjs",
+    "check:leaks": "node scripts/check-leaks.mjs",
+    "rules:show": "node scripts/show-rules.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.0"
+  }
 }

package/index.js

@@ -1,2 +0,0 @@
-"use strict";
-module.exports = { name: "viafrei", status: "reserved" };