@spurtest/cli 0.1.5
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 +123 -0
- package/dist/api.js +64 -0
- package/dist/auth.js +165 -0
- package/dist/config.js +50 -0
- package/dist/connector.js +343 -0
- package/dist/index.js +125 -0
- package/dist/proxy.js +29 -0
- package/dist/run.js +158 -0
- package/package.json +37 -0
package/README.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Spur CLI
|
|
2
|
+
|
|
3
|
+
Run Spur tests from your terminal or CI, including against `localhost` and internal hosts.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx @spurtest/cli login
|
|
7
|
+
spur tests # your tests and their ids
|
|
8
|
+
spur run 123 456 -e Staging # run and wait; exit code 0 = all passed
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Testing localhost and internal hosts
|
|
12
|
+
|
|
13
|
+
Spur's browsers run in Spur's cloud. A **tunnel** lets them reach hosts that only your machine or network can reach.
|
|
14
|
+
Tests keep their own URLs: a test that opens `http://localhost:3000` still opens `http://localhost:3000`.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# For one run: shares localhost:3000 while the run lasts
|
|
18
|
+
spur run 123 -e Local --tunnel localhost:3000
|
|
19
|
+
|
|
20
|
+
# Run a test written for staging against your local app instead
|
|
21
|
+
spur run 123 -e Staging --url localhost:3000
|
|
22
|
+
|
|
23
|
+
# Several hosts, e.g. a frontend and an internal API
|
|
24
|
+
spur run 123 -e Local --tunnel localhost:3000 --tunnel api.internal:8080
|
|
25
|
+
|
|
26
|
+
# Keep a tunnel open for many runs (and for runs started from Spur or an AI agent)
|
|
27
|
+
spur tunnel start localhost:3000 api.internal:8080 --name checkout-dev
|
|
28
|
+
spur run 123 -e Local --tunnel checkout-dev
|
|
29
|
+
spur tunnel list
|
|
30
|
+
spur tunnel stop checkout-dev
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The tunnel is one outbound HTTPS connection from your machine to Spur. Nothing is exposed to the internet, there's no
|
|
34
|
+
firewall change, and it only connects to the hosts you list. An unnamed tunnel is revoked when the command exits.
|
|
35
|
+
|
|
36
|
+
## Always-on connector (Docker)
|
|
37
|
+
|
|
38
|
+
For hosts that scheduled runs, the Spur UI or CI need around the clock (internal staging, an on-prem system), run the
|
|
39
|
+
connector inside your network as a container. It keeps a **named** tunnel open and reconnects on its own.
|
|
40
|
+
|
|
41
|
+
Create the tunnel once (name it on Spur's **Tunnels** page, or run `spur tunnel start <hosts> --name <name>` once),
|
|
42
|
+
then choose **Connector key → Generate** on that tunnel. The key is shown once; it can only start that one tunnel, so
|
|
43
|
+
it's safe to leave in a container. Then:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
docker run -d --restart=always --name spur-connector \
|
|
47
|
+
-e SPUR_CONNECTOR_KEY=spur_conn_... \
|
|
48
|
+
-e SPUR_TUNNEL_HOSTS="staging.internal:8080,api.internal:443" \
|
|
49
|
+
ghcr.io/tryspur-dev/spur-connector:latest
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
| Variable | Required | Meaning |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `SPUR_CONNECTOR_KEY` | yes | The tunnel's connector key, from the Tunnels page |
|
|
55
|
+
| `SPUR_TUNNEL_NAME` | no | The tunnel's name; optional (and must match the key's tunnel if set) |
|
|
56
|
+
| `SPUR_TUNNEL_HOSTS` | yes | Hosts to share, comma or space separated, each `host:port` (a bare host shares ports 80 and 443) |
|
|
57
|
+
| `HTTPS_PROXY` / `NO_PROXY` | no | Corporate proxy for the connection to Spur |
|
|
58
|
+
|
|
59
|
+
The container only needs outbound HTTPS to Spur, and network access to the hosts it shares. It stops cleanly on
|
|
60
|
+
`docker stop`; the named tunnel stays, so restarting picks it up again. Rotating the key on the Tunnels page keeps
|
|
61
|
+
the running connector connected but stops it reconnecting with the old key; stopping the tunnel revokes the key. Once
|
|
62
|
+
Spur refuses the tunnel, or another connector takes it over, the container exits non-zero so your restart policy or
|
|
63
|
+
orchestrator sees it.
|
|
64
|
+
|
|
65
|
+
docker-compose:
|
|
66
|
+
|
|
67
|
+
```yaml
|
|
68
|
+
services:
|
|
69
|
+
spur-connector:
|
|
70
|
+
image: ghcr.io/tryspur-dev/spur-connector:latest
|
|
71
|
+
restart: always
|
|
72
|
+
environment:
|
|
73
|
+
SPUR_CONNECTOR_KEY: ${SPUR_CONNECTOR_KEY}
|
|
74
|
+
SPUR_TUNNEL_HOSTS: staging.internal:8080,api.internal:443
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Kubernetes:
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
apiVersion: v1
|
|
81
|
+
kind: Secret
|
|
82
|
+
metadata: { name: spur-connector }
|
|
83
|
+
stringData: { SPUR_CONNECTOR_KEY: spur_conn_... }
|
|
84
|
+
---
|
|
85
|
+
apiVersion: apps/v1
|
|
86
|
+
kind: Deployment
|
|
87
|
+
metadata: { name: spur-connector }
|
|
88
|
+
spec:
|
|
89
|
+
replicas: 1 # one connector per tunnel name: a second one takes the tunnel over
|
|
90
|
+
selector: { matchLabels: { app: spur-connector } }
|
|
91
|
+
template:
|
|
92
|
+
metadata: { labels: { app: spur-connector } }
|
|
93
|
+
spec:
|
|
94
|
+
containers:
|
|
95
|
+
- name: connector
|
|
96
|
+
image: ghcr.io/tryspur-dev/spur-connector:latest
|
|
97
|
+
env:
|
|
98
|
+
- { name: SPUR_TUNNEL_HOSTS, value: "staging.internal:8080,api.internal:443" }
|
|
99
|
+
envFrom: [{ secretRef: { name: spur-connector } }]
|
|
100
|
+
resources: { requests: { cpu: 50m, memory: 64Mi }, limits: { memory: 256Mi } }
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Behind a corporate proxy
|
|
104
|
+
|
|
105
|
+
If your network only allows outbound traffic through an HTTP proxy, set `HTTPS_PROXY` (or `HTTP_PROXY`) and,
|
|
106
|
+
if needed, `NO_PROXY`. Both the CLI's calls to Spur and the tunnel's connection to Spur's relay use it; the tunnel's
|
|
107
|
+
connections to your own shared hosts never do. For a proxy that inspects TLS with its own certificate authority, also
|
|
108
|
+
set `NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem`.
|
|
109
|
+
|
|
110
|
+
## CI
|
|
111
|
+
|
|
112
|
+
Create a Spur API key (**Integrations → MCP → API key** in Spur) and set it as `SPUR_API_KEY`:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npx -y @spurtest/cli run 123 456 -e Preview --url "$PREVIEW_URL" -H "x-vercel-protection-bypass=$BYPASS" --junit spur.xml
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
| Exit code | Meaning |
|
|
119
|
+
|---|---|
|
|
120
|
+
| 0 | every test passed |
|
|
121
|
+
| 1 | a test failed or did not run |
|
|
122
|
+
| 2 | Spur, the tunnel, or the timeout failed |
|
|
123
|
+
| 130 | interrupted (the run keeps going in Spur) |
|
package/dist/api.js
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
2
|
+
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
|
|
3
|
+
import { accessToken, refresh } from "./auth.js";
|
|
4
|
+
import { proxiedFetch } from "./proxy.js";
|
|
5
|
+
export class ApiError extends Error {
|
|
6
|
+
status;
|
|
7
|
+
constructor(message, status) {
|
|
8
|
+
super(message);
|
|
9
|
+
this.status = status;
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
export class SpurApi {
|
|
13
|
+
server;
|
|
14
|
+
connectorKey;
|
|
15
|
+
/** With a connector key the client can only start that key's tunnel: no login, no refresh. */
|
|
16
|
+
constructor(server, connectorKey) {
|
|
17
|
+
this.server = server;
|
|
18
|
+
this.connectorKey = connectorKey;
|
|
19
|
+
}
|
|
20
|
+
async request(method, path, body) {
|
|
21
|
+
let response = await this.send(method, path, body, this.connectorKey ?? (await accessToken(this.server)));
|
|
22
|
+
// A token revoked or expired early: refresh once (an API key or connector key has nothing to refresh).
|
|
23
|
+
if (response.status === 401 && !this.connectorKey && !process.env.SPUR_API_KEY) {
|
|
24
|
+
response = await this.send(method, path, body, await refresh(this.server));
|
|
25
|
+
}
|
|
26
|
+
if (response.status === 204)
|
|
27
|
+
return undefined;
|
|
28
|
+
const payload = (await response.json().catch(() => ({})));
|
|
29
|
+
if (!response.ok) {
|
|
30
|
+
throw new ApiError(payload.error || `${method} ${path} failed with ${response.status}`, response.status);
|
|
31
|
+
}
|
|
32
|
+
return payload;
|
|
33
|
+
}
|
|
34
|
+
send(method, path, body, token) {
|
|
35
|
+
return proxiedFetch(`${this.server}${path}`, {
|
|
36
|
+
method,
|
|
37
|
+
headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
|
|
38
|
+
body: body === undefined ? undefined : JSON.stringify(body),
|
|
39
|
+
signal: AbortSignal.timeout(90_000),
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
/** One MCP tool call, for the commands that just show what the tool says (applications, tests, environments). */
|
|
43
|
+
async tool(name, args = {}) {
|
|
44
|
+
const transport = new StreamableHTTPClientTransport(new URL(`${this.server}/api/mcp`), {
|
|
45
|
+
requestInit: { headers: { Authorization: `Bearer ${await accessToken(this.server)}` } },
|
|
46
|
+
fetch: proxiedFetch,
|
|
47
|
+
});
|
|
48
|
+
const client = new Client({ name: "spur-cli", version: "0.1.5" });
|
|
49
|
+
await client.connect(transport);
|
|
50
|
+
try {
|
|
51
|
+
const result = await client.callTool({ name, arguments: args });
|
|
52
|
+
const text = result.content
|
|
53
|
+
.filter((part) => part.type === "text" && part.text)
|
|
54
|
+
.map((part) => part.text)
|
|
55
|
+
.join("\n");
|
|
56
|
+
if (result.isError)
|
|
57
|
+
throw new ApiError(text || `${name} failed`, 400);
|
|
58
|
+
return text;
|
|
59
|
+
}
|
|
60
|
+
finally {
|
|
61
|
+
await client.close();
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
package/dist/auth.js
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { randomBytes } from "node:crypto";
|
|
3
|
+
import { createServer } from "node:http";
|
|
4
|
+
import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
|
|
5
|
+
import { readLogin, writeLogin } from "./config.js";
|
|
6
|
+
import { proxiedFetch } from "./proxy.js";
|
|
7
|
+
// Refresh this long before the access token expires, so a request never goes out with a token about to lapse.
|
|
8
|
+
const REFRESH_EARLY_MS = 60_000;
|
|
9
|
+
const LOGIN_TIMEOUT_MS = 5 * 60_000;
|
|
10
|
+
export class NotLoggedInError extends Error {
|
|
11
|
+
constructor() {
|
|
12
|
+
super("Not logged in. Run `spur login`, or set SPUR_API_KEY (a Spur API key from Integrations → MCP → API key).");
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
/** Keeps the OAuth state in ~/.config/spur/login.json. Spur's MCP server is the OAuth resource, as for any MCP client. */
|
|
16
|
+
class FileProvider {
|
|
17
|
+
login;
|
|
18
|
+
port;
|
|
19
|
+
verifier = "";
|
|
20
|
+
expectedState = randomBytes(16).toString("hex");
|
|
21
|
+
constructor(login, port) {
|
|
22
|
+
this.login = login;
|
|
23
|
+
this.port = port;
|
|
24
|
+
}
|
|
25
|
+
// Always set: the SDK treats a provider without one as a client-credentials client and never refreshes. Outside
|
|
26
|
+
// `spur login` it is the registered one, and a full re-authorization stops at redirectToAuthorization.
|
|
27
|
+
get redirectUrl() {
|
|
28
|
+
if (this.port)
|
|
29
|
+
return `http://127.0.0.1:${this.port}/callback`;
|
|
30
|
+
const registered = this.login.client && "redirect_uris" in this.login.client ? this.login.client.redirect_uris?.[0] : undefined;
|
|
31
|
+
return registered ? String(registered) : "http://127.0.0.1/callback";
|
|
32
|
+
}
|
|
33
|
+
get clientMetadata() {
|
|
34
|
+
return {
|
|
35
|
+
client_name: "Spur CLI",
|
|
36
|
+
redirect_uris: this.redirectUrl ? [this.redirectUrl] : [],
|
|
37
|
+
grant_types: ["authorization_code", "refresh_token"],
|
|
38
|
+
response_types: ["code"],
|
|
39
|
+
token_endpoint_auth_method: "none",
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
state() {
|
|
43
|
+
return this.expectedState;
|
|
44
|
+
}
|
|
45
|
+
checkState(state) {
|
|
46
|
+
return state === this.expectedState;
|
|
47
|
+
}
|
|
48
|
+
clientInformation() {
|
|
49
|
+
return this.login.client;
|
|
50
|
+
}
|
|
51
|
+
async saveClientInformation(client) {
|
|
52
|
+
this.login.client = client;
|
|
53
|
+
await writeLogin(this.login);
|
|
54
|
+
}
|
|
55
|
+
tokens() {
|
|
56
|
+
return this.login.tokens;
|
|
57
|
+
}
|
|
58
|
+
async saveTokens(tokens) {
|
|
59
|
+
this.login.tokens = { ...tokens, obtained_at: Date.now() };
|
|
60
|
+
await writeLogin(this.login);
|
|
61
|
+
}
|
|
62
|
+
redirectToAuthorization(url) {
|
|
63
|
+
if (!this.port) {
|
|
64
|
+
// A refresh that fell back to a fresh authorization: only `spur login` can open a browser.
|
|
65
|
+
throw new NotLoggedInError();
|
|
66
|
+
}
|
|
67
|
+
console.log(`Opening your browser to log in. If it does not open, visit:\n ${url.href}\n`);
|
|
68
|
+
openBrowser(url.href);
|
|
69
|
+
}
|
|
70
|
+
saveCodeVerifier(verifier) {
|
|
71
|
+
this.verifier = verifier;
|
|
72
|
+
}
|
|
73
|
+
codeVerifier() {
|
|
74
|
+
return this.verifier;
|
|
75
|
+
}
|
|
76
|
+
saveDiscoveryState(state) {
|
|
77
|
+
this.login.discovery = state;
|
|
78
|
+
}
|
|
79
|
+
discoveryState() {
|
|
80
|
+
return this.login.discovery;
|
|
81
|
+
}
|
|
82
|
+
async invalidateCredentials(scope) {
|
|
83
|
+
if (scope === "all" || scope === "client")
|
|
84
|
+
delete this.login.client;
|
|
85
|
+
if (scope === "all" || scope === "tokens")
|
|
86
|
+
delete this.login.tokens;
|
|
87
|
+
if (scope === "all" || scope === "discovery")
|
|
88
|
+
delete this.login.discovery;
|
|
89
|
+
await writeLogin(this.login);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
function openBrowser(url) {
|
|
93
|
+
const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
|
|
94
|
+
const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
|
|
95
|
+
try {
|
|
96
|
+
spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
// The URL is already printed.
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
const mcpUrl = (server) => `${server}/api/mcp`;
|
|
103
|
+
export async function login(server) {
|
|
104
|
+
const callback = createServer();
|
|
105
|
+
await new Promise((resolve) => callback.listen(0, "127.0.0.1", resolve));
|
|
106
|
+
const { port } = callback.address();
|
|
107
|
+
// A fresh registration each time: the loopback port is part of the registered redirect URI.
|
|
108
|
+
const saved = { server };
|
|
109
|
+
const provider = new FileProvider(saved, port);
|
|
110
|
+
try {
|
|
111
|
+
const code = new Promise((resolve, reject) => {
|
|
112
|
+
const timer = setTimeout(() => reject(new Error("Timed out waiting for the browser login.")), LOGIN_TIMEOUT_MS);
|
|
113
|
+
callback.on("request", (request, response) => {
|
|
114
|
+
const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`);
|
|
115
|
+
if (url.pathname !== "/callback") {
|
|
116
|
+
response.writeHead(404).end();
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
const received = url.searchParams.get("code");
|
|
120
|
+
const ok = received && provider.checkState(url.searchParams.get("state"));
|
|
121
|
+
response.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
|
|
122
|
+
response.end(ok ? "<p>Logged in to Spur. You can close this tab.</p>" : "<p>Login failed. Run <code>spur login</code> again.</p>");
|
|
123
|
+
clearTimeout(timer);
|
|
124
|
+
if (ok)
|
|
125
|
+
resolve(received);
|
|
126
|
+
else
|
|
127
|
+
reject(new Error(url.searchParams.get("error_description") || url.searchParams.get("error") || "Login failed."));
|
|
128
|
+
});
|
|
129
|
+
});
|
|
130
|
+
if ((await auth(provider, { serverUrl: mcpUrl(server), fetchFn: proxiedFetch })) === "AUTHORIZED")
|
|
131
|
+
return;
|
|
132
|
+
await auth(provider, { serverUrl: mcpUrl(server), authorizationCode: await code, fetchFn: proxiedFetch });
|
|
133
|
+
}
|
|
134
|
+
finally {
|
|
135
|
+
callback.close();
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
/** SPUR_API_KEY for CI; otherwise the saved login, refreshed when it is about to expire. */
|
|
139
|
+
export class ConnectorKeyOnlyError extends Error {
|
|
140
|
+
constructor() {
|
|
141
|
+
super("A connector key can only start its tunnel. Use spur login or SPUR_API_KEY for other commands.");
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
export async function accessToken(server) {
|
|
145
|
+
if (process.env.SPUR_API_KEY)
|
|
146
|
+
return process.env.SPUR_API_KEY;
|
|
147
|
+
const saved = await readLogin();
|
|
148
|
+
if (!saved?.tokens || saved.server !== server) {
|
|
149
|
+
throw process.env.SPUR_CONNECTOR_KEY ? new ConnectorKeyOnlyError() : new NotLoggedInError();
|
|
150
|
+
}
|
|
151
|
+
const { obtained_at, expires_in } = saved.tokens;
|
|
152
|
+
const expiresAt = obtained_at && expires_in ? obtained_at + expires_in * 1000 : Number.POSITIVE_INFINITY;
|
|
153
|
+
if (Date.now() < expiresAt - REFRESH_EARLY_MS)
|
|
154
|
+
return saved.tokens.access_token;
|
|
155
|
+
return refresh(server, saved);
|
|
156
|
+
}
|
|
157
|
+
export async function refresh(server, saved) {
|
|
158
|
+
const login = saved ?? (await readLogin());
|
|
159
|
+
if (!login?.tokens?.refresh_token || login.server !== server)
|
|
160
|
+
throw new NotLoggedInError();
|
|
161
|
+
const provider = new FileProvider(login, null);
|
|
162
|
+
if ((await auth(provider, { serverUrl: mcpUrl(server), fetchFn: proxiedFetch })) !== "AUTHORIZED" || !login.tokens)
|
|
163
|
+
throw new NotLoggedInError();
|
|
164
|
+
return login.tokens.access_token;
|
|
165
|
+
}
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
export const DEFAULT_SERVER = "https://app.spurtest.com";
|
|
5
|
+
const configDir = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "spur");
|
|
6
|
+
const loginFile = () => join(configDir(), "login.json");
|
|
7
|
+
export async function readLogin() {
|
|
8
|
+
try {
|
|
9
|
+
return JSON.parse(await readFile(loginFile(), "utf8"));
|
|
10
|
+
}
|
|
11
|
+
catch {
|
|
12
|
+
return null;
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
export async function writeLogin(login) {
|
|
16
|
+
const file = loginFile();
|
|
17
|
+
await mkdir(dirname(file), { recursive: true, mode: 0o700 });
|
|
18
|
+
await writeFile(file, JSON.stringify(login, null, 2), { mode: 0o600 });
|
|
19
|
+
await chmod(file, 0o600);
|
|
20
|
+
}
|
|
21
|
+
export async function clearLogin() {
|
|
22
|
+
await rm(loginFile(), { force: true });
|
|
23
|
+
}
|
|
24
|
+
// The CLI sends API keys and logins to this server, so only Spur's own apps (and a client run locally) are accepted:
|
|
25
|
+
// a typo or a phishing instruction can't redirect a key elsewhere.
|
|
26
|
+
export const DEV_SERVER = "https://spurdev-client.vercel.app";
|
|
27
|
+
const SPUR_SERVERS = new Set([DEFAULT_SERVER, DEV_SERVER]);
|
|
28
|
+
const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "host.docker.internal"]);
|
|
29
|
+
export function checkServer(server) {
|
|
30
|
+
let url;
|
|
31
|
+
try {
|
|
32
|
+
url = new URL(server);
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
throw new Error(`"${server}" isn't a URL.`);
|
|
36
|
+
}
|
|
37
|
+
const local = url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
|
|
38
|
+
if (!SPUR_SERVERS.has(url.origin) && !local) {
|
|
39
|
+
throw new Error(`${url.origin} isn't a Spur server. Use ${DEFAULT_SERVER} (the default) or ${DEV_SERVER}.`);
|
|
40
|
+
}
|
|
41
|
+
return url.origin;
|
|
42
|
+
}
|
|
43
|
+
/** Where `spur login` goes: --server, then SPUR_SERVER, then Spur's. Never the last login, so a past dev login doesn't stick. */
|
|
44
|
+
export function loginServer(flag) {
|
|
45
|
+
return checkServer(flag || process.env.SPUR_SERVER || DEFAULT_SERVER);
|
|
46
|
+
}
|
|
47
|
+
/** --server, then SPUR_SERVER, then the server you logged in to, then Spur's. */
|
|
48
|
+
export async function resolveServer(flag) {
|
|
49
|
+
return checkServer(flag || process.env.SPUR_SERVER || (await readLogin())?.server || DEFAULT_SERVER);
|
|
50
|
+
}
|
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
import net from "node:net";
|
|
2
|
+
import WebSocket from "ws";
|
|
3
|
+
import { proxyAgentFor } from "./proxy.js";
|
|
4
|
+
// The connector side of a Spur tunnel. It keeps one outbound WebSocket to Spur's relay; for each stream the relay
|
|
5
|
+
// opens, it connects to one of the shared hosts and copies bytes both ways. TLS, if any, stays end to end inside the stream.
|
|
6
|
+
export const FRAME = { OPEN: 1, OPEN_OK: 2, OPEN_FAIL: 3, DATA: 4, CLOSE: 5 };
|
|
7
|
+
const MAX_PAYLOAD = 65536;
|
|
8
|
+
// Stop reading from local sockets while this much is queued on the WebSocket.
|
|
9
|
+
const HIGH_WATER = 8 * 1024 * 1024;
|
|
10
|
+
const RETRY_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
|
|
11
|
+
// Failed attempts before start() gives up (and, with keepTrying, keeps retrying in the background).
|
|
12
|
+
const START_ATTEMPTS = 3;
|
|
13
|
+
// How long a relay may take to answer the hello before the attempt counts as failed.
|
|
14
|
+
const READY_TIMEOUT_MS = 15_000;
|
|
15
|
+
// Once one relay is ready, how long start waits for the others before reporting them as retrying.
|
|
16
|
+
const OTHERS_GRACE_MS = 1_000;
|
|
17
|
+
export function encodeFrame(type, stream, payload = Buffer.alloc(0)) {
|
|
18
|
+
const header = Buffer.alloc(5);
|
|
19
|
+
header.writeUInt8(type, 0);
|
|
20
|
+
header.writeUInt32BE(stream, 1);
|
|
21
|
+
return Buffer.concat([header, payload]);
|
|
22
|
+
}
|
|
23
|
+
export function decodeFrame(frame) {
|
|
24
|
+
if (frame.length < 5)
|
|
25
|
+
return null;
|
|
26
|
+
return { type: frame.readUInt8(0), stream: frame.readUInt32BE(1), payload: frame.subarray(5) };
|
|
27
|
+
}
|
|
28
|
+
const LOCAL_NAMES = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1", "[::1]"]);
|
|
29
|
+
export function isLocalHost(host) {
|
|
30
|
+
return LOCAL_NAMES.has(host) || host.endsWith(".localhost");
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* `localhost:3000` → [localhost:3000]; `http://app.internal` → [app.internal:80]; `app.internal` → [:80, :443].
|
|
34
|
+
* The relay matches `host:port` exactly, so every entry carries a port.
|
|
35
|
+
*/
|
|
36
|
+
export function parseHostSpec(spec) {
|
|
37
|
+
const value = spec.trim().toLowerCase();
|
|
38
|
+
if (value.includes("://")) {
|
|
39
|
+
const url = new URL(value);
|
|
40
|
+
const port = url.port || (url.protocol === "https:" || url.protocol === "wss:" ? "443" : "80");
|
|
41
|
+
return [`${url.hostname}:${port}`];
|
|
42
|
+
}
|
|
43
|
+
const colon = value.lastIndexOf(":");
|
|
44
|
+
const bracketed = value.startsWith("[");
|
|
45
|
+
if (colon > 0 && (!bracketed || value.lastIndexOf("]") < colon)) {
|
|
46
|
+
const port = Number(value.slice(colon + 1));
|
|
47
|
+
if (!Number.isInteger(port) || port < 1 || port > 65535)
|
|
48
|
+
throw new Error(`"${spec}" has no valid port.`);
|
|
49
|
+
return [`${value.slice(0, colon)}:${port}`];
|
|
50
|
+
}
|
|
51
|
+
if (!value)
|
|
52
|
+
throw new Error("Empty host.");
|
|
53
|
+
return [`${value}:80`, `${value}:443`];
|
|
54
|
+
}
|
|
55
|
+
/** Looks like a host to share rather than a tunnel name or id. */
|
|
56
|
+
export function looksLikeHost(value) {
|
|
57
|
+
return value.includes(":") || value.includes("://") || isLocalHost(value.toLowerCase());
|
|
58
|
+
}
|
|
59
|
+
function splitHostPort(target) {
|
|
60
|
+
const colon = target.lastIndexOf(":");
|
|
61
|
+
const host = target.slice(0, colon);
|
|
62
|
+
return { host: host.startsWith("[") ? host.slice(1, -1) : host, port: Number(target.slice(colon + 1)) };
|
|
63
|
+
}
|
|
64
|
+
export class Connector {
|
|
65
|
+
tunnel;
|
|
66
|
+
hosts;
|
|
67
|
+
log;
|
|
68
|
+
relayUrl;
|
|
69
|
+
retryMs;
|
|
70
|
+
readyTimeoutMs;
|
|
71
|
+
socket = null;
|
|
72
|
+
streams = new Map();
|
|
73
|
+
stopped = false;
|
|
74
|
+
attempt = 0;
|
|
75
|
+
endWith = () => { };
|
|
76
|
+
/** Resolves with the reason once Spur refuses the tunnel or another connector takes it over; never after stop(). */
|
|
77
|
+
ended = new Promise((resolve) => {
|
|
78
|
+
this.endWith = resolve;
|
|
79
|
+
});
|
|
80
|
+
constructor(tunnel, hosts, log, relayUrl = process.env.SPUR_RELAY_URL || tunnel.relay_url, retryMs = RETRY_MS, readyTimeoutMs = READY_TIMEOUT_MS) {
|
|
81
|
+
this.tunnel = tunnel;
|
|
82
|
+
this.hosts = hosts;
|
|
83
|
+
this.log = log;
|
|
84
|
+
this.relayUrl = relayUrl;
|
|
85
|
+
this.retryMs = retryMs;
|
|
86
|
+
this.readyTimeoutMs = readyTimeoutMs;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Resolves once the relay accepts the tunnel and keeps reconnecting after that until stop(). Rejects after
|
|
90
|
+
* START_ATTEMPTS failed attempts; with keepTrying it still retries in the background and logs when it later connects.
|
|
91
|
+
*/
|
|
92
|
+
start(options = {}) {
|
|
93
|
+
return new Promise((resolve, reject) => {
|
|
94
|
+
let ready = false;
|
|
95
|
+
let settled = false;
|
|
96
|
+
let failures = 0;
|
|
97
|
+
const end = (reason) => {
|
|
98
|
+
this.stopped = true;
|
|
99
|
+
this.endWith(reason);
|
|
100
|
+
if (!settled) {
|
|
101
|
+
settled = true;
|
|
102
|
+
reject(new Error(reason));
|
|
103
|
+
}
|
|
104
|
+
else
|
|
105
|
+
this.log(reason);
|
|
106
|
+
};
|
|
107
|
+
const connect = () => {
|
|
108
|
+
const ws = new WebSocket(this.relayUrl, { handshakeTimeout: 15_000, agent: proxyAgentFor(this.relayUrl) });
|
|
109
|
+
this.socket = ws;
|
|
110
|
+
let lastError = "";
|
|
111
|
+
let readyTimer;
|
|
112
|
+
let readyHere = false;
|
|
113
|
+
ws.on("open", () => {
|
|
114
|
+
ws.send(JSON.stringify({ type: "hello", version: 1, tunnel_id: this.tunnel.id, token: this.tunnel.token, hosts: this.hosts }));
|
|
115
|
+
// A relay that accepts the socket but never answers the hello counts as a failed attempt.
|
|
116
|
+
readyTimer = setTimeout(() => {
|
|
117
|
+
lastError = `no answer within ${this.readyTimeoutMs / 1000}s`;
|
|
118
|
+
ws.terminate();
|
|
119
|
+
}, this.readyTimeoutMs);
|
|
120
|
+
});
|
|
121
|
+
ws.on("message", (data, isBinary) => {
|
|
122
|
+
if (!isBinary) {
|
|
123
|
+
const message = JSON.parse(data.toString());
|
|
124
|
+
if (message.type === "ready") {
|
|
125
|
+
clearTimeout(readyTimer);
|
|
126
|
+
readyHere = true;
|
|
127
|
+
this.attempt = 0;
|
|
128
|
+
if (!ready) {
|
|
129
|
+
ready = true;
|
|
130
|
+
// A relay that was unreachable at start connected later, in the background.
|
|
131
|
+
if (settled)
|
|
132
|
+
this.log("Connected to Spur.");
|
|
133
|
+
settled = true;
|
|
134
|
+
resolve();
|
|
135
|
+
}
|
|
136
|
+
else {
|
|
137
|
+
this.log("Reconnected to Spur.");
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
else if (message.type === "error") {
|
|
141
|
+
end(`Spur refused the tunnel: ${message.message ?? "unknown error"}`);
|
|
142
|
+
}
|
|
143
|
+
return;
|
|
144
|
+
}
|
|
145
|
+
this.onFrame(data);
|
|
146
|
+
});
|
|
147
|
+
ws.on("close", (code, reason) => {
|
|
148
|
+
clearTimeout(readyTimer);
|
|
149
|
+
this.closeAllStreams();
|
|
150
|
+
if (this.stopped)
|
|
151
|
+
return;
|
|
152
|
+
if (code === 4409) {
|
|
153
|
+
end("Another `spur tunnel start` took over this tunnel. Stopping here.");
|
|
154
|
+
return;
|
|
155
|
+
}
|
|
156
|
+
// Any close before ready (refused socket, 1011/1013 from a relay that can't check the tunnel yet, a
|
|
157
|
+
// silent relay) is a failed attempt; only the first few decide whether start() fails.
|
|
158
|
+
if (!readyHere && ++failures === START_ATTEMPTS && !settled) {
|
|
159
|
+
settled = true;
|
|
160
|
+
if (!options.keepTrying)
|
|
161
|
+
this.stopped = true;
|
|
162
|
+
const why = lastError || `closed with ${code}${reason.length ? ` ${reason.toString()}` : ""}`;
|
|
163
|
+
reject(new Error(`Could not reach Spur's relay at ${this.relayUrl}: ${why}`));
|
|
164
|
+
if (this.stopped)
|
|
165
|
+
return;
|
|
166
|
+
}
|
|
167
|
+
const wait = this.retryMs[Math.min(this.attempt++, this.retryMs.length - 1)];
|
|
168
|
+
if (ready)
|
|
169
|
+
this.log(`Lost the connection to Spur. Retrying in ${wait / 1000}s…`);
|
|
170
|
+
setTimeout(() => {
|
|
171
|
+
if (!this.stopped)
|
|
172
|
+
connect();
|
|
173
|
+
}, wait);
|
|
174
|
+
});
|
|
175
|
+
ws.on("error", (error) => {
|
|
176
|
+
// A close event follows and counts the attempt.
|
|
177
|
+
lastError = error.message;
|
|
178
|
+
});
|
|
179
|
+
};
|
|
180
|
+
connect();
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
async stop() {
|
|
184
|
+
this.stopped = true;
|
|
185
|
+
this.closeAllStreams();
|
|
186
|
+
this.socket?.close(1000);
|
|
187
|
+
}
|
|
188
|
+
send(type, stream, payload) {
|
|
189
|
+
if (this.socket?.readyState === WebSocket.OPEN)
|
|
190
|
+
this.socket.send(encodeFrame(type, stream, payload));
|
|
191
|
+
}
|
|
192
|
+
onFrame(data) {
|
|
193
|
+
const frame = decodeFrame(data);
|
|
194
|
+
if (!frame)
|
|
195
|
+
return;
|
|
196
|
+
const { type, stream, payload } = frame;
|
|
197
|
+
if (type === FRAME.OPEN)
|
|
198
|
+
this.open(stream, payload.toString("utf8").toLowerCase());
|
|
199
|
+
else if (type === FRAME.DATA)
|
|
200
|
+
this.streams.get(stream)?.write(payload);
|
|
201
|
+
else if (type === FRAME.CLOSE) {
|
|
202
|
+
this.streams.get(stream)?.end();
|
|
203
|
+
this.streams.delete(stream);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
open(stream, target) {
|
|
207
|
+
if (!this.hosts.includes(target)) {
|
|
208
|
+
this.log(`Refused ${target}: not shared.`);
|
|
209
|
+
this.send(FRAME.OPEN_FAIL, stream, Buffer.from("host not shared"));
|
|
210
|
+
return;
|
|
211
|
+
}
|
|
212
|
+
const { host, port } = splitHostPort(target);
|
|
213
|
+
const local = net.connect({ host, port, autoSelectFamily: true });
|
|
214
|
+
this.streams.set(stream, local);
|
|
215
|
+
let opened = false;
|
|
216
|
+
local.on("connect", () => {
|
|
217
|
+
opened = true;
|
|
218
|
+
this.log(`Opened ${target}.`);
|
|
219
|
+
this.send(FRAME.OPEN_OK, stream);
|
|
220
|
+
});
|
|
221
|
+
local.on("data", (chunk) => {
|
|
222
|
+
for (let at = 0; at < chunk.length; at += MAX_PAYLOAD)
|
|
223
|
+
this.send(FRAME.DATA, stream, chunk.subarray(at, at + MAX_PAYLOAD));
|
|
224
|
+
if ((this.socket?.bufferedAmount ?? 0) > HIGH_WATER) {
|
|
225
|
+
local.pause();
|
|
226
|
+
const resume = setInterval(() => {
|
|
227
|
+
if ((this.socket?.bufferedAmount ?? 0) < HIGH_WATER / 2 || local.destroyed) {
|
|
228
|
+
clearInterval(resume);
|
|
229
|
+
local.resume();
|
|
230
|
+
}
|
|
231
|
+
}, 50);
|
|
232
|
+
}
|
|
233
|
+
});
|
|
234
|
+
local.on("error", (error) => {
|
|
235
|
+
if (opened)
|
|
236
|
+
return;
|
|
237
|
+
this.log(`Could not reach ${target}: ${error.message}`);
|
|
238
|
+
this.send(FRAME.OPEN_FAIL, stream, Buffer.from(`${target}: ${error.message}`));
|
|
239
|
+
});
|
|
240
|
+
local.on("close", () => {
|
|
241
|
+
if (opened && this.streams.has(stream))
|
|
242
|
+
this.send(FRAME.CLOSE, stream);
|
|
243
|
+
this.streams.delete(stream);
|
|
244
|
+
});
|
|
245
|
+
}
|
|
246
|
+
closeAllStreams() {
|
|
247
|
+
for (const local of this.streams.values())
|
|
248
|
+
local.destroy();
|
|
249
|
+
this.streams.clear();
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
/** Every relay the connector should reach: SPUR_RELAY_URL wins, then the server's list, then its single relay_url. */
|
|
253
|
+
export function relaysFor(tunnel) {
|
|
254
|
+
if (process.env.SPUR_RELAY_URL)
|
|
255
|
+
return [{ region: "default", url: process.env.SPUR_RELAY_URL }];
|
|
256
|
+
if (tunnel.relays?.length)
|
|
257
|
+
return tunnel.relays;
|
|
258
|
+
return tunnel.relay_url ? [{ region: "default", url: tunnel.relay_url }] : [];
|
|
259
|
+
}
|
|
260
|
+
/** `connected: us, in; retrying: others`, or "" for a single relay. */
|
|
261
|
+
export function regionStatus(handle) {
|
|
262
|
+
if (handle.connected.length + handle.retrying.length < 2)
|
|
263
|
+
return "";
|
|
264
|
+
const parts = [`connected: ${handle.connected.join(", ")}`];
|
|
265
|
+
if (handle.retrying.length)
|
|
266
|
+
parts.push(`retrying: ${handle.retrying.join(", ")}`);
|
|
267
|
+
return ` (${parts.join("; ")})`;
|
|
268
|
+
}
|
|
269
|
+
/**
|
|
270
|
+
* Creates (or, for a name, resumes) a tunnel and connects it to every relay, so a run in any region finds it. Starts once
|
|
271
|
+
* at least one relay accepts it; the others keep retrying in the background. Unnamed tunnels are revoked by `close`.
|
|
272
|
+
*/
|
|
273
|
+
export async function startTunnel(api, specs, name, log, options = {}) {
|
|
274
|
+
const hosts = [...new Set(specs.flatMap(parseHostSpec))];
|
|
275
|
+
const tunnel = await api.request("POST", "/api/cli/tunnels", { hosts, ...(name ? { name } : {}) });
|
|
276
|
+
const relays = relaysFor(tunnel);
|
|
277
|
+
// A connector key's tunnel is named and outlives this process; only an unnamed tunnel is revoked on close.
|
|
278
|
+
const revocable = !api.connectorKey && !tunnel.name;
|
|
279
|
+
const revoke = async () => {
|
|
280
|
+
if (revocable)
|
|
281
|
+
await api.request("DELETE", `/api/cli/tunnels?tunnel=${encodeURIComponent(tunnel.id)}`).catch(() => undefined);
|
|
282
|
+
};
|
|
283
|
+
if (!relays.length) {
|
|
284
|
+
await revoke();
|
|
285
|
+
throw new Error("Spur returned no relay for this tunnel.");
|
|
286
|
+
}
|
|
287
|
+
const many = relays.length > 1;
|
|
288
|
+
const connectors = relays.map((relay) => new Connector(tunnel, hosts, many ? (message) => log(`${relay.region}: ${message}`) : log, relay.url, options.retryMs, options.readyTimeoutMs));
|
|
289
|
+
const outcomes = relays.map(() => ({ status: "pending" }));
|
|
290
|
+
// After start returns, relays that were still connecting log how they settled.
|
|
291
|
+
let started = false;
|
|
292
|
+
const failed = (region, error) => error.message.startsWith("Spur refused") ? error.message : `Could not reach the ${region} relay yet; retrying in the background (${error.message}).`;
|
|
293
|
+
// Starts as soon as one relay is ready (after a short grace for the others), or once every relay has failed.
|
|
294
|
+
await new Promise((resolve) => {
|
|
295
|
+
let grace;
|
|
296
|
+
const check = () => {
|
|
297
|
+
if (outcomes.every((outcome) => outcome.status !== "pending")) {
|
|
298
|
+
clearTimeout(grace);
|
|
299
|
+
resolve();
|
|
300
|
+
}
|
|
301
|
+
else if (!grace && outcomes.some((outcome) => outcome.status === "ready")) {
|
|
302
|
+
grace = setTimeout(resolve, options.graceMs ?? OTHERS_GRACE_MS);
|
|
303
|
+
}
|
|
304
|
+
};
|
|
305
|
+
connectors.forEach((connector, index) => {
|
|
306
|
+
connector.start({ keepTrying: many }).then(() => {
|
|
307
|
+
outcomes[index] = { status: "ready" };
|
|
308
|
+
if (started)
|
|
309
|
+
log(`${relays[index]?.region}: Connected to Spur.`);
|
|
310
|
+
check();
|
|
311
|
+
}, (error) => {
|
|
312
|
+
outcomes[index] = { status: "failed", error };
|
|
313
|
+
if (started)
|
|
314
|
+
log(`${relays[index]?.region}: ${failed(relays[index]?.region ?? "", error)}`);
|
|
315
|
+
check();
|
|
316
|
+
});
|
|
317
|
+
});
|
|
318
|
+
});
|
|
319
|
+
const connected = relays.filter((_, index) => outcomes[index]?.status === "ready").map((relay) => relay.region);
|
|
320
|
+
const failures = outcomes.flatMap((outcome, index) => (outcome.status === "failed" ? [{ region: relays[index]?.region ?? "", error: outcome.error }] : []));
|
|
321
|
+
const stopAll = () => Promise.all(connectors.map((connector) => connector.stop()));
|
|
322
|
+
// A refusal (revoked tunnel, tunnels not enabled) is final everywhere; only unreachable relays are worth retrying.
|
|
323
|
+
const refused = failures.find((failure) => failure.error.message.startsWith("Spur refused"));
|
|
324
|
+
if (!connected.length || refused) {
|
|
325
|
+
await stopAll();
|
|
326
|
+
await revoke();
|
|
327
|
+
throw refused?.error ?? failures[0]?.error ?? new Error("Could not reach Spur's relay.");
|
|
328
|
+
}
|
|
329
|
+
for (const failure of failures)
|
|
330
|
+
log(failed(failure.region, failure.error));
|
|
331
|
+
started = true;
|
|
332
|
+
return {
|
|
333
|
+
tunnel,
|
|
334
|
+
hosts,
|
|
335
|
+
connected,
|
|
336
|
+
retrying: relays.filter((_, index) => outcomes[index]?.status !== "ready").map((relay) => relay.region),
|
|
337
|
+
ended: Promise.all(connectors.map((connector) => connector.ended)).then((reasons) => reasons[0] ?? "Stopped."),
|
|
338
|
+
close: async () => {
|
|
339
|
+
await stopAll();
|
|
340
|
+
await revoke();
|
|
341
|
+
},
|
|
342
|
+
};
|
|
343
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { Command, Option } from "commander";
|
|
3
|
+
import { SpurApi } from "./api.js";
|
|
4
|
+
import { login } from "./auth.js";
|
|
5
|
+
import { clearLogin, loginServer, resolveServer } from "./config.js";
|
|
6
|
+
import { regionStatus, startTunnel } from "./connector.js";
|
|
7
|
+
import { EXIT, run } from "./run.js";
|
|
8
|
+
const program = new Command()
|
|
9
|
+
.name("spur")
|
|
10
|
+
.description("Run Spur tests from your terminal and CI, including against localhost.")
|
|
11
|
+
.version("0.1.5")
|
|
12
|
+
.option("--server <url>", "Spur app URL (or SPUR_SERVER)");
|
|
13
|
+
const api = async () => new SpurApi(await resolveServer(program.opts().server));
|
|
14
|
+
program
|
|
15
|
+
.command("login")
|
|
16
|
+
.description("Log in with your browser. CI uses SPUR_API_KEY instead.")
|
|
17
|
+
.action(async () => {
|
|
18
|
+
const server = loginServer(program.opts().server);
|
|
19
|
+
await login(server);
|
|
20
|
+
console.log(`Logged in to ${server}.`);
|
|
21
|
+
});
|
|
22
|
+
program
|
|
23
|
+
.command("logout")
|
|
24
|
+
.description("Forget the saved login.")
|
|
25
|
+
.action(async () => {
|
|
26
|
+
await clearLogin();
|
|
27
|
+
console.log("Logged out.");
|
|
28
|
+
});
|
|
29
|
+
program
|
|
30
|
+
.command("apps")
|
|
31
|
+
.argument("[name]", "switch to this application")
|
|
32
|
+
.description("List your applications, or switch the active one.")
|
|
33
|
+
.action(async (name) => {
|
|
34
|
+
console.log(await (await api()).tool("applications", name ? { application_name: name } : {}));
|
|
35
|
+
});
|
|
36
|
+
program
|
|
37
|
+
.command("tests")
|
|
38
|
+
.argument("[test-id]", "show one test: its environments, viewports and scenarios")
|
|
39
|
+
.description("List the active application's tests.")
|
|
40
|
+
.action(async (testId) => {
|
|
41
|
+
console.log(await (await api()).tool("list_tests", testId ? { test_id: Number(testId) } : {}));
|
|
42
|
+
});
|
|
43
|
+
program
|
|
44
|
+
.command("envs")
|
|
45
|
+
.description("List the active application's environments.")
|
|
46
|
+
.action(async () => {
|
|
47
|
+
console.log(await (await api()).tool("list_environments"));
|
|
48
|
+
});
|
|
49
|
+
const collect = (value, previous) => [...previous, value];
|
|
50
|
+
program
|
|
51
|
+
.command("run")
|
|
52
|
+
.argument("<test-ids...>", "test ids, from `spur tests`")
|
|
53
|
+
.description("Run tests and wait for the result. Tests on localhost or internal hosts go through a Spur tunnel (--tunnel).")
|
|
54
|
+
.requiredOption("-e, --env <name>", "environment, from `spur envs`")
|
|
55
|
+
.option("-u, --url <url>", "run against this URL instead of the environment's (a localhost URL is shared through a tunnel)")
|
|
56
|
+
.option("--map <domain=url>", "send one environment domain to another URL (repeatable)", collect, [])
|
|
57
|
+
.option("-H, --header <name=value>", "header sent only to the --url/--map hosts, e.g. a preview bypass (repeatable)", collect, [])
|
|
58
|
+
.option("-t, --tunnel <host|name>", "share a host such as localhost:3000 for this run, or use a started tunnel (repeatable)", collect, [])
|
|
59
|
+
.option("--scenario <row>", "scenario table row, for tests that have one")
|
|
60
|
+
.addOption(new Option("--viewport <viewport>").choices(["web_desktop", "web_mobile", "native_ios", "native_android"]))
|
|
61
|
+
.addOption(new Option("--browser <browser>").choices(["chrome", "webkit", "msedge", "firefox"]))
|
|
62
|
+
.option("--name <name>", "run name")
|
|
63
|
+
.option("--no-wait", "start the run and exit")
|
|
64
|
+
.option("--timeout <duration>", "stop waiting after this long", "60m")
|
|
65
|
+
.option("--json", "print the result as JSON")
|
|
66
|
+
.option("--junit <file>", "write a JUnit XML report")
|
|
67
|
+
.action(async (ids, options) => {
|
|
68
|
+
const testIds = ids.map((id) => {
|
|
69
|
+
const value = Number(id);
|
|
70
|
+
if (!Number.isInteger(value) || value <= 0)
|
|
71
|
+
throw new Error(`"${id}" is not a test id.`);
|
|
72
|
+
return value;
|
|
73
|
+
});
|
|
74
|
+
process.exitCode = await run(await api(), testIds, options);
|
|
75
|
+
});
|
|
76
|
+
const tunnel = program.command("tunnel").description("Share local or internal hosts with Spur's cloud browsers. Tests keep their own URLs.");
|
|
77
|
+
tunnel
|
|
78
|
+
.command("start")
|
|
79
|
+
.argument("<hosts...>", "hosts to share, e.g. localhost:3000 api.internal:8080")
|
|
80
|
+
.option("--name <name>", "keep the tunnel after this command exits, so runs and later starts can reuse it")
|
|
81
|
+
.description("Open a tunnel and keep it open until you press Ctrl+C. SPUR_CONNECTOR_KEY starts that key's tunnel without a login.")
|
|
82
|
+
.action(async (hosts, options) => {
|
|
83
|
+
const connectorKey = process.env.SPUR_CONNECTOR_KEY || undefined;
|
|
84
|
+
const client = connectorKey ? new SpurApi(await resolveServer(program.opts().server), connectorKey) : await api();
|
|
85
|
+
const started = await startTunnel(client, hosts, options.name, console.log);
|
|
86
|
+
const label = started.tunnel.name ?? started.tunnel.id;
|
|
87
|
+
console.log(`Tunnel ${label} is sharing ${started.hosts.join(", ")}${regionStatus(started)}.`);
|
|
88
|
+
console.log(`Run tests through it with: spur run <test-ids> -e <env> --tunnel ${label}`);
|
|
89
|
+
console.log("Press Ctrl+C to stop.");
|
|
90
|
+
// Waits for Ctrl+C, or for every relay to stop for good, so a container's restart policy sees the exit.
|
|
91
|
+
const ended = await new Promise((resolve) => {
|
|
92
|
+
process.once("SIGINT", () => resolve(null));
|
|
93
|
+
process.once("SIGTERM", () => resolve(null));
|
|
94
|
+
started.ended.then(resolve);
|
|
95
|
+
});
|
|
96
|
+
await started.close();
|
|
97
|
+
if (ended)
|
|
98
|
+
throw new Error(`Tunnel ${label} stopped: ${ended}`);
|
|
99
|
+
console.log(started.tunnel.name ? `Disconnected. Start it again with --name ${started.tunnel.name}.` : "Tunnel closed.");
|
|
100
|
+
});
|
|
101
|
+
tunnel
|
|
102
|
+
.command("list")
|
|
103
|
+
.description("List your team's open tunnels.")
|
|
104
|
+
.action(async () => {
|
|
105
|
+
const { tunnels } = await (await api()).request("GET", "/api/cli/tunnels");
|
|
106
|
+
if (!tunnels.length) {
|
|
107
|
+
console.log("No open tunnels.");
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
for (const item of tunnels) {
|
|
111
|
+
console.log(`${item.name ?? item.id} ${item.hosts.join(", ")} ${item.created_by_email ?? ""} last connected ${item.last_connected_at ?? "never"}`);
|
|
112
|
+
}
|
|
113
|
+
});
|
|
114
|
+
tunnel
|
|
115
|
+
.command("stop")
|
|
116
|
+
.argument("<name-or-id>")
|
|
117
|
+
.description("Close a tunnel for good: runs can no longer use it.")
|
|
118
|
+
.action(async (nameOrId) => {
|
|
119
|
+
await (await api()).request("DELETE", `/api/cli/tunnels?tunnel=${encodeURIComponent(nameOrId)}`);
|
|
120
|
+
console.log(`Stopped ${nameOrId}.`);
|
|
121
|
+
});
|
|
122
|
+
program.parseAsync().catch((error) => {
|
|
123
|
+
console.error(error instanceof Error ? error.message : String(error));
|
|
124
|
+
process.exitCode = EXIT.error;
|
|
125
|
+
});
|
package/dist/proxy.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { HttpsProxyAgent } from "https-proxy-agent";
|
|
2
|
+
import { getProxyForUrl } from "proxy-from-env";
|
|
3
|
+
import { ProxyAgent, fetch as undiciFetch } from "undici";
|
|
4
|
+
// Corporate networks often allow outbound traffic only through an HTTP proxy. The CLI honours the usual variables:
|
|
5
|
+
// HTTPS_PROXY / HTTP_PROXY (either case) and NO_PROXY. Connections to the hosts a tunnel shares never use the proxy.
|
|
6
|
+
/** The proxy for this URL, or "" when none applies. WebSocket URLs use the HTTP(S) variables. */
|
|
7
|
+
export function proxyFor(url) {
|
|
8
|
+
const lookup = url.startsWith("wss:") ? `https:${url.slice(4)}` : url.startsWith("ws:") ? `http:${url.slice(3)}` : url;
|
|
9
|
+
return getProxyForUrl(lookup);
|
|
10
|
+
}
|
|
11
|
+
/** The agent for the relay WebSocket, or undefined when no proxy applies to that URL. */
|
|
12
|
+
export function proxyAgentFor(url) {
|
|
13
|
+
const proxy = proxyFor(url);
|
|
14
|
+
return proxy ? new HttpsProxyAgent(proxy) : undefined;
|
|
15
|
+
}
|
|
16
|
+
const dispatchers = new Map();
|
|
17
|
+
/** fetch for the CLI's API and MCP calls: through the proxy the environment names for that URL, if any. */
|
|
18
|
+
export const proxiedFetch = (input, init) => {
|
|
19
|
+
const url = typeof input === "string" ? input : input.href;
|
|
20
|
+
const proxy = proxyFor(url);
|
|
21
|
+
if (!proxy)
|
|
22
|
+
return fetch(input, init);
|
|
23
|
+
let dispatcher = dispatchers.get(proxy);
|
|
24
|
+
if (!dispatcher) {
|
|
25
|
+
dispatcher = new ProxyAgent(proxy);
|
|
26
|
+
dispatchers.set(proxy, dispatcher);
|
|
27
|
+
}
|
|
28
|
+
return undiciFetch(input, { ...init, dispatcher });
|
|
29
|
+
};
|
package/dist/run.js
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
import { writeFile } from "node:fs/promises";
|
|
2
|
+
import { setTimeout as sleep } from "node:timers/promises";
|
|
3
|
+
import { ApiError } from "./api.js";
|
|
4
|
+
import { isLocalHost, looksLikeHost, regionStatus, startTunnel } from "./connector.js";
|
|
5
|
+
const POLL_MS = 5_000;
|
|
6
|
+
const MAX_POLL_FAILURES = 6;
|
|
7
|
+
// Exit codes: 0 every test passed, 1 a test failed or did not run, 2 Spur or the tunnel failed, 130 interrupted.
|
|
8
|
+
export const EXIT = { pass: 0, fail: 1, error: 2, interrupted: 130 };
|
|
9
|
+
export function parsePairs(values, flag) {
|
|
10
|
+
const pairs = {};
|
|
11
|
+
for (const value of values) {
|
|
12
|
+
const at = value.indexOf("=");
|
|
13
|
+
if (at <= 0)
|
|
14
|
+
throw new Error(`${flag} takes name=value, got "${value}".`);
|
|
15
|
+
pairs[value.slice(0, at)] = value.slice(at + 1);
|
|
16
|
+
}
|
|
17
|
+
return pairs;
|
|
18
|
+
}
|
|
19
|
+
export function parseDuration(value) {
|
|
20
|
+
const units = { s: 1_000, m: 60_000, h: 3_600_000 };
|
|
21
|
+
const unit = units[value.slice(-1)];
|
|
22
|
+
const amount = Number(unit ? value.slice(0, -1) : value);
|
|
23
|
+
if (!Number.isFinite(amount) || amount <= 0)
|
|
24
|
+
throw new Error(`--timeout takes a duration like 30m, got "${value}".`);
|
|
25
|
+
return amount * (unit ?? 60_000);
|
|
26
|
+
}
|
|
27
|
+
function toUrl(value) {
|
|
28
|
+
return new URL(value.includes("://") ? value : `${value.startsWith("localhost") || value.startsWith("127.") ? "http" : "https"}://${value}`);
|
|
29
|
+
}
|
|
30
|
+
export const passed = (test) => test.progress?.toUpperCase() === "COMPLETE" && test.outcome?.toUpperCase() === "PASS";
|
|
31
|
+
export async function run(api, testIds, options) {
|
|
32
|
+
const timeoutMs = parseDuration(options.timeout);
|
|
33
|
+
const headers = parsePairs(options.header, "--header");
|
|
34
|
+
const domains = parsePairs(options.map, "--map");
|
|
35
|
+
const url = options.url ? toUrl(options.url) : undefined;
|
|
36
|
+
const localUrl = url && isLocalHost(url.hostname) ? url : undefined;
|
|
37
|
+
// --tunnel takes hosts to share for this run, or the name/id of a tunnel already started with `spur tunnel start`.
|
|
38
|
+
// A localhost --url with no --tunnel shares that host.
|
|
39
|
+
const tunnelArgs = options.tunnel.length ? options.tunnel : localUrl ? [localUrl.host] : [];
|
|
40
|
+
const sharesHosts = tunnelArgs.length > 0 && tunnelArgs.every(looksLikeHost);
|
|
41
|
+
if (tunnelArgs.length > 1 && !sharesHosts)
|
|
42
|
+
throw new Error("--tunnel takes either hosts to share or one tunnel name or id.");
|
|
43
|
+
if (sharesHosts && !options.wait)
|
|
44
|
+
throw new Error("--no-wait can't share hosts: the tunnel closes when `spur run` exits. Use `spur tunnel start --name`.");
|
|
45
|
+
let tunnel = sharesHosts ? undefined : tunnelArgs[0];
|
|
46
|
+
let closeTunnel;
|
|
47
|
+
let interrupted = false;
|
|
48
|
+
const onSignal = () => {
|
|
49
|
+
interrupted = true;
|
|
50
|
+
};
|
|
51
|
+
process.once("SIGINT", onSignal);
|
|
52
|
+
process.once("SIGTERM", onSignal);
|
|
53
|
+
try {
|
|
54
|
+
if (sharesHosts) {
|
|
55
|
+
const started = await startTunnel(api, tunnelArgs, undefined, (message) => log(options, message));
|
|
56
|
+
closeTunnel = started.close;
|
|
57
|
+
tunnel = started.tunnel.id;
|
|
58
|
+
log(options, `Sharing ${started.hosts.join(", ")} with Spur for this run${regionStatus(started)}.`);
|
|
59
|
+
}
|
|
60
|
+
const started = await api.request("POST", "/api/cli/runs", {
|
|
61
|
+
tests: testIds.map((test_id) => ({
|
|
62
|
+
test_id,
|
|
63
|
+
env_name: options.env,
|
|
64
|
+
...(options.scenario ? { scenario_row_name: options.scenario } : {}),
|
|
65
|
+
...(options.viewport ? { viewport: options.viewport } : {}),
|
|
66
|
+
...(options.browser ? { browser: options.browser } : {}),
|
|
67
|
+
})),
|
|
68
|
+
...(options.name ? { run_name: options.name } : {}),
|
|
69
|
+
...(url ? { override_url: url.href.endsWith("/") ? url.href.slice(0, -1) : url.href } : {}),
|
|
70
|
+
...(Object.keys(domains).length ? { domain_overrides: domains } : {}),
|
|
71
|
+
...(Object.keys(headers).length ? { override_headers: headers } : {}),
|
|
72
|
+
...(tunnel ? { tunnel } : {}),
|
|
73
|
+
});
|
|
74
|
+
log(options, `Started run ${started.request_id}`);
|
|
75
|
+
if (started.dispatch_uncertain)
|
|
76
|
+
log(options, "Spur could not confirm the run started; checking on it instead of starting it again.");
|
|
77
|
+
if (!options.wait) {
|
|
78
|
+
if (options.json)
|
|
79
|
+
console.log(JSON.stringify({ request_id: started.request_id }));
|
|
80
|
+
return EXIT.pass;
|
|
81
|
+
}
|
|
82
|
+
const deadline = Date.now() + timeoutMs;
|
|
83
|
+
const reported = new Set();
|
|
84
|
+
let status = { state: "queued", tests: [] };
|
|
85
|
+
let failures = 0;
|
|
86
|
+
while (!interrupted && Date.now() < deadline) {
|
|
87
|
+
try {
|
|
88
|
+
status = await api.request("GET", `/api/cli/runs?request_id=${started.request_id}`);
|
|
89
|
+
failures = 0;
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
// A blip while polling must not fail a run that is still going: retry a few times first.
|
|
93
|
+
if (++failures > MAX_POLL_FAILURES || (error instanceof ApiError && error.status < 500 && error.status !== 429))
|
|
94
|
+
throw error;
|
|
95
|
+
await sleep(POLL_MS);
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
for (const test of status.tests) {
|
|
99
|
+
const key = `${test.test_id}|${test.scenario ?? ""}|${test.progress}|${test.outcome}`;
|
|
100
|
+
if (!reported.has(key) && !options.json) {
|
|
101
|
+
reported.add(key);
|
|
102
|
+
console.log(describe(test));
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
if (status.state === "completed")
|
|
106
|
+
break;
|
|
107
|
+
await sleep(POLL_MS);
|
|
108
|
+
}
|
|
109
|
+
// Spur can add tests to a run (a suite's dependent tests); only the ones asked for decide the result.
|
|
110
|
+
const asked = status.tests.filter((test) => testIds.includes(test.test_id));
|
|
111
|
+
if (options.junit)
|
|
112
|
+
await writeFile(options.junit, junit(asked, status.state !== "completed"));
|
|
113
|
+
if (options.json)
|
|
114
|
+
console.log(JSON.stringify({ request_id: started.request_id, ...status }, null, 2));
|
|
115
|
+
if (interrupted) {
|
|
116
|
+
log(options, "Stopped waiting. The run keeps going in Spur.");
|
|
117
|
+
return EXIT.interrupted;
|
|
118
|
+
}
|
|
119
|
+
if (status.state !== "completed") {
|
|
120
|
+
log(options, `Timed out after ${options.timeout}. The run keeps going in Spur.`);
|
|
121
|
+
return EXIT.error;
|
|
122
|
+
}
|
|
123
|
+
const failed = asked.filter((test) => !passed(test));
|
|
124
|
+
const extra = status.tests.length - asked.length;
|
|
125
|
+
log(options, `\n${asked.length - failed.length} passed, ${failed.length} failed or did not run.${extra ? ` (${extra} other test${extra === 1 ? "" : "s"} Spur added to the run not counted.)` : ""}`);
|
|
126
|
+
return failed.length || !asked.length ? EXIT.fail : EXIT.pass;
|
|
127
|
+
}
|
|
128
|
+
finally {
|
|
129
|
+
process.off("SIGINT", onSignal);
|
|
130
|
+
process.off("SIGTERM", onSignal);
|
|
131
|
+
await closeTunnel?.();
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
function log(options, message) {
|
|
135
|
+
// --json keeps stdout parseable.
|
|
136
|
+
(options.json ? console.error : console.log)(message);
|
|
137
|
+
}
|
|
138
|
+
function describe(test) {
|
|
139
|
+
const name = test.scenario ? `${test.name} [${test.scenario}]` : test.name;
|
|
140
|
+
const progress = test.progress?.toUpperCase() ?? "QUEUED";
|
|
141
|
+
if (progress !== "COMPLETE")
|
|
142
|
+
return `… ${name}: ${progress.toLowerCase().replaceAll("_", " ")}${test.reason ? ` (${test.reason})` : ""}`;
|
|
143
|
+
const mark = passed(test) ? "✓" : "✗";
|
|
144
|
+
return `${mark} ${name}${!passed(test) && test.reason ? `\n ${test.reason}` : ""}${test.url ? `\n ${test.url}` : ""}`;
|
|
145
|
+
}
|
|
146
|
+
const xml = (value) => value.replace(/[<>&"']/g, (c) => ({ "<": "<", ">": ">", "&": "&", '"': """, "'": "'" })[c]);
|
|
147
|
+
export function junit(tests, timedOut) {
|
|
148
|
+
const failures = tests.filter((test) => !passed(test)).length;
|
|
149
|
+
const cases = tests.map((test) => {
|
|
150
|
+
const name = xml(test.scenario ? `${test.name} [${test.scenario}]` : test.name);
|
|
151
|
+
const body = passed(test)
|
|
152
|
+
? ""
|
|
153
|
+
: `<failure message="${xml(test.reason ?? test.progress ?? "did not finish")}">${xml(test.url ?? "")}</failure>`;
|
|
154
|
+
return ` <testcase classname="spur" name="${name}">${body}${test.url ? `<system-out>${xml(test.url)}</system-out>` : ""}</testcase>`;
|
|
155
|
+
});
|
|
156
|
+
const error = timedOut ? ' errors="1"' : "";
|
|
157
|
+
return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n <testsuite name="spur" tests="${tests.length}" failures="${failures}"${error}>\n${cases.join("\n")}\n </testsuite>\n</testsuites>\n`;
|
|
158
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@spurtest/cli",
|
|
3
|
+
"version": "0.1.5",
|
|
4
|
+
"description": "Run Spur tests from your terminal and CI, including against localhost.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"spur": "dist/index.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"dist"
|
|
11
|
+
],
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=20"
|
|
14
|
+
},
|
|
15
|
+
"scripts": {
|
|
16
|
+
"build": "rm -rf dist && tsc -p tsconfig.json",
|
|
17
|
+
"test": "npm run build && node --test --experimental-strip-types --no-warnings test/*.test.ts"
|
|
18
|
+
},
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
21
|
+
"commander": "15.1.0",
|
|
22
|
+
"https-proxy-agent": "^7.0.6",
|
|
23
|
+
"proxy-from-env": "^1.1.0",
|
|
24
|
+
"undici": "^6.21.3",
|
|
25
|
+
"ws": "^8.18.3"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@types/node": "^22",
|
|
29
|
+
"@types/proxy-from-env": "^1.0.4",
|
|
30
|
+
"@types/ws": "^8.18.1",
|
|
31
|
+
"typescript": "^5.9"
|
|
32
|
+
},
|
|
33
|
+
"license": "UNLICENSED",
|
|
34
|
+
"publishConfig": {
|
|
35
|
+
"access": "public"
|
|
36
|
+
}
|
|
37
|
+
}
|