pi-farm 0.2.1 → 0.2.3
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 +44 -1
- package/bin/pp.js +5 -0
- package/completions/_pp +6 -0
- package/completions/pp.bash +13 -4
- package/docs/architecture.md +151 -0
- package/docs/autostart.md +166 -0
- package/docs/cli.md +207 -0
- package/docs/configuration.md +160 -0
- package/docs/development.md +129 -0
- package/docs/troubleshooting.md +204 -0
- package/package.json +2 -1
- package/src/autostart.js +7 -1
- package/src/commands.js +297 -0
- package/src/help.js +42 -0
- package/src/mesh.js +224 -0
package/src/mesh.js
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
import { connect } from "node:net";
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { homedir } from "node:os";
|
|
4
|
+
import { join } from "node:path";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Minimal, dependency-free client for the local remote-pi mesh broker.
|
|
8
|
+
*
|
|
9
|
+
* The broker speaks JSON lines over a UNIX socket
|
|
10
|
+
* (`~/.pi/remote/sessions/local/broker.sock`). Three frames are enough for a
|
|
11
|
+
* CLI: an unregistered `list_peers` probe (read-only — no registration, no
|
|
12
|
+
* peer_joined/peer_left broadcast), a `register` handshake, and routed
|
|
13
|
+
* envelopes. Cross-PC delivery rides the leader's relay bridge, so a local
|
|
14
|
+
* peer can address `macbook:/path@name` without pairing anything itself.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
export const DEFAULT_ACK_TIMEOUT_MS = 5000;
|
|
18
|
+
export const BROADCAST_TARGET = "broadcast";
|
|
19
|
+
|
|
20
|
+
export class MeshError extends Error {
|
|
21
|
+
constructor(message, code = "mesh") {
|
|
22
|
+
super(message);
|
|
23
|
+
this.name = "MeshError";
|
|
24
|
+
this.code = code;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Absolute path of the local broker socket (`REMOTE_PI_HOME` aware). */
|
|
29
|
+
export function brokerSockPath(env = process.env) {
|
|
30
|
+
const home = env.REMOTE_PI_HOME || homedir();
|
|
31
|
+
return join(home, ".pi", "remote", "sessions", "local", "broker.sock");
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** `<pc>:` prefix of a cross-PC address, or null for a local one. */
|
|
35
|
+
export function peerPc(address) {
|
|
36
|
+
if (typeof address !== "string") return null;
|
|
37
|
+
const match = /^([A-Za-z0-9._-]+):\//.exec(address);
|
|
38
|
+
return match ? match[1] : null;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The address a configured session registers as (`<cwd>@<name>`), or null. */
|
|
42
|
+
export function sessionMeshAddress(session) {
|
|
43
|
+
if (!session || !session.remotePiName) return null;
|
|
44
|
+
if (session.remotePiMode === "off") return null;
|
|
45
|
+
return `${session.cwd}@${session.remotePiName}`;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Live peer addresses that belong to `address`. The broker appends `#N` when
|
|
50
|
+
* two agents in the same directory ask for the same name, so an exact match is
|
|
51
|
+
* not enough.
|
|
52
|
+
*/
|
|
53
|
+
export function livePeersFor(peers, address) {
|
|
54
|
+
if (!address) return [];
|
|
55
|
+
return peers.filter((peer) => peer === address || peer.startsWith(`${address}#`));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function attachLineReader(socket, onMessage) {
|
|
59
|
+
let buffer = "";
|
|
60
|
+
socket.setEncoding("utf8");
|
|
61
|
+
socket.on("data", (chunk) => {
|
|
62
|
+
buffer += chunk;
|
|
63
|
+
let index;
|
|
64
|
+
while ((index = buffer.indexOf("\n")) >= 0) {
|
|
65
|
+
const line = buffer.slice(0, index).trim();
|
|
66
|
+
buffer = buffer.slice(index + 1);
|
|
67
|
+
if (!line) continue;
|
|
68
|
+
let message;
|
|
69
|
+
try {
|
|
70
|
+
message = JSON.parse(line);
|
|
71
|
+
} catch {
|
|
72
|
+
continue; // a broken line must not kill the session
|
|
73
|
+
}
|
|
74
|
+
if (message && typeof message === "object") onMessage(message);
|
|
75
|
+
}
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function connectSocket(sockPath, onError) {
|
|
80
|
+
const socket = connect(sockPath);
|
|
81
|
+
socket.once("error", (error) => {
|
|
82
|
+
const code = error && typeof error === "object" ? error.code : undefined;
|
|
83
|
+
onError(
|
|
84
|
+
new MeshError(
|
|
85
|
+
code === "ENOENT" || code === "ECONNREFUSED"
|
|
86
|
+
? `no mesh broker at ${sockPath} (start remote-pi inside a pi session, or run "/remote-pi")`
|
|
87
|
+
: `cannot reach mesh broker at ${sockPath}: ${code ?? error.message}`,
|
|
88
|
+
code === "ENOENT" || code === "ECONNREFUSED" ? "no_broker" : "socket",
|
|
89
|
+
),
|
|
90
|
+
);
|
|
91
|
+
});
|
|
92
|
+
return socket;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Read-only roster query. Registers nothing and broadcasts nothing, so it is
|
|
97
|
+
* safe to call from any script at any time.
|
|
98
|
+
*/
|
|
99
|
+
export function probePeers({ sockPath = brokerSockPath(), timeoutMs = 3000 } = {}) {
|
|
100
|
+
return new Promise((resolve, reject) => {
|
|
101
|
+
let settled = false;
|
|
102
|
+
const finish = (error, value) => {
|
|
103
|
+
if (settled) return;
|
|
104
|
+
settled = true;
|
|
105
|
+
clearTimeout(timer);
|
|
106
|
+
socket.destroy();
|
|
107
|
+
if (error) reject(error);
|
|
108
|
+
else resolve(value);
|
|
109
|
+
};
|
|
110
|
+
const timer = setTimeout(
|
|
111
|
+
() => finish(new MeshError(`no reply from mesh broker at ${sockPath} within ${timeoutMs}ms`, "timeout")),
|
|
112
|
+
timeoutMs,
|
|
113
|
+
);
|
|
114
|
+
const socket = connectSocket(sockPath, (error) => finish(error));
|
|
115
|
+
attachLineReader(socket, (message) => {
|
|
116
|
+
if (message.body && message.body.type === "list_peers_reply") {
|
|
117
|
+
finish(null, Array.isArray(message.body.peers) ? message.body.peers.filter((p) => typeof p === "string") : []);
|
|
118
|
+
}
|
|
119
|
+
});
|
|
120
|
+
socket.write(`${JSON.stringify({ type: "list_peers" })}\n`);
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Join the mesh as an ephemeral peer. Resolves once the broker assigns an
|
|
126
|
+
* address; the returned handle can send envelopes and wait for their ACK.
|
|
127
|
+
*/
|
|
128
|
+
export function connectPeer({ sockPath = brokerSockPath(), name = "pp-mesh", cwd = process.cwd(), timeoutMs = 5000 } = {}) {
|
|
129
|
+
return new Promise((resolve, reject) => {
|
|
130
|
+
const pendingAcks = new Map();
|
|
131
|
+
const listeners = new Set();
|
|
132
|
+
let address = null;
|
|
133
|
+
let assignedName = null;
|
|
134
|
+
let settled = false;
|
|
135
|
+
|
|
136
|
+
const socket = connectSocket(sockPath, (error) => {
|
|
137
|
+
if (!settled) {
|
|
138
|
+
settled = true;
|
|
139
|
+
clearTimeout(timer);
|
|
140
|
+
socket.destroy();
|
|
141
|
+
reject(error);
|
|
142
|
+
}
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
const timer = setTimeout(() => {
|
|
146
|
+
if (settled) return;
|
|
147
|
+
settled = true;
|
|
148
|
+
socket.destroy();
|
|
149
|
+
reject(new MeshError(`mesh broker did not acknowledge the registration of "${name}" within ${timeoutMs}ms`, "timeout"));
|
|
150
|
+
}, timeoutMs);
|
|
151
|
+
|
|
152
|
+
attachLineReader(socket, (message) => {
|
|
153
|
+
if (!settled) {
|
|
154
|
+
if (message.type === "register_ack" && typeof message.address_assigned === "string") {
|
|
155
|
+
settled = true;
|
|
156
|
+
clearTimeout(timer);
|
|
157
|
+
address = message.address_assigned;
|
|
158
|
+
assignedName = typeof message.name_assigned === "string" ? message.name_assigned : address;
|
|
159
|
+
resolve({
|
|
160
|
+
socket,
|
|
161
|
+
address,
|
|
162
|
+
name: assignedName,
|
|
163
|
+
onMessage(handler) {
|
|
164
|
+
listeners.add(handler);
|
|
165
|
+
return () => listeners.delete(handler);
|
|
166
|
+
},
|
|
167
|
+
send(to, body, re = null) {
|
|
168
|
+
return sendRaw(socket, address, to, body, re);
|
|
169
|
+
},
|
|
170
|
+
waitAck(id, ms = DEFAULT_ACK_TIMEOUT_MS) {
|
|
171
|
+
return new Promise((done) => {
|
|
172
|
+
const ackTimer = setTimeout(() => {
|
|
173
|
+
pendingAcks.delete(id);
|
|
174
|
+
done({ status: "timeout", id });
|
|
175
|
+
}, ms);
|
|
176
|
+
pendingAcks.set(id, (result) => {
|
|
177
|
+
clearTimeout(ackTimer);
|
|
178
|
+
done(result);
|
|
179
|
+
});
|
|
180
|
+
});
|
|
181
|
+
},
|
|
182
|
+
async sendWithAck(to, body, ms = DEFAULT_ACK_TIMEOUT_MS, re = null) {
|
|
183
|
+
const id = sendRaw(socket, address, to, body, re);
|
|
184
|
+
const result = await this.waitAck(id, ms);
|
|
185
|
+
return { ...result, id };
|
|
186
|
+
},
|
|
187
|
+
close() {
|
|
188
|
+
try {
|
|
189
|
+
socket.end();
|
|
190
|
+
} catch {
|
|
191
|
+
/* already gone */
|
|
192
|
+
}
|
|
193
|
+
},
|
|
194
|
+
});
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
if (message.type !== "peer_joined" && message.type !== "peer_left") {
|
|
198
|
+
settled = true;
|
|
199
|
+
clearTimeout(timer);
|
|
200
|
+
socket.destroy();
|
|
201
|
+
reject(new MeshError(`unexpected frame during registration: ${JSON.stringify(message).slice(0, 120)}`, "protocol"));
|
|
202
|
+
}
|
|
203
|
+
return;
|
|
204
|
+
}
|
|
205
|
+
if (message.body && message.body.type === "ack" && typeof message.re === "string") {
|
|
206
|
+
const waiter = pendingAcks.get(message.re);
|
|
207
|
+
if (waiter) {
|
|
208
|
+
pendingAcks.delete(message.re);
|
|
209
|
+
waiter({ status: message.body.status ?? "received", target: message.body.target, id: message.re });
|
|
210
|
+
}
|
|
211
|
+
return;
|
|
212
|
+
}
|
|
213
|
+
for (const listener of listeners) listener(message);
|
|
214
|
+
});
|
|
215
|
+
|
|
216
|
+
socket.write(`${JSON.stringify({ type: "register", name, cwd })}\n`);
|
|
217
|
+
});
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
function sendRaw(socket, from, to, body, re = null) {
|
|
221
|
+
const id = randomUUID();
|
|
222
|
+
socket.write(`${JSON.stringify({ from, to, id, re, body })}\n`);
|
|
223
|
+
return id;
|
|
224
|
+
}
|