@pmndre/pine 0.22.0 → 0.33.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.
Files changed (99) hide show
  1. package/README.md +2 -1
  2. package/changes.json +265 -0
  3. package/docs/SKILL.md +31 -7
  4. package/docs/references/agents.md +245 -21
  5. package/docs/references/coding.md +1 -1
  6. package/docs/references/computer.md +1 -1
  7. package/docs/references/configuration.md +14 -5
  8. package/docs/references/mcp.md +9 -0
  9. package/docs/references/operations.md +20 -9
  10. package/docs/references/overview.md +3 -1
  11. package/docs/references/security.md +83 -24
  12. package/docs/references/setup.md +55 -9
  13. package/docs/references/source-types.md +1418 -0
  14. package/docs/references/sources.md +333 -19
  15. package/docs/references/stack.md +1 -0
  16. package/docs/references/tui.md +86 -12
  17. package/examples/home/AGENTS.md +4 -0
  18. package/examples/home/TOOLS.md +5 -0
  19. package/examples/home/agents/main/workspace/AGENTS.md +1 -1
  20. package/examples/home/agents/main/workspace/TOOLS.md +5 -0
  21. package/mcp/browser.d.ts +6 -0
  22. package/mcp/browser.js +19 -0
  23. package/mcp/render.d.ts +1 -0
  24. package/mcp/render.js +237 -0
  25. package/package.json +3 -1
  26. package/src/actions.d.ts +6 -1
  27. package/src/actions.js +17 -4
  28. package/src/admin.d.ts +4 -0
  29. package/src/admin.js +25 -6
  30. package/src/agents.d.ts +167 -2
  31. package/src/agents.js +912 -45
  32. package/src/catalogue.d.ts +60 -0
  33. package/src/catalogue.js +791 -0
  34. package/src/cli.js +10 -7
  35. package/src/config.d.ts +53 -4
  36. package/src/config.js +30 -5
  37. package/src/goals.d.ts +1 -1
  38. package/src/goals.js +14 -1
  39. package/src/manual.js +24 -2
  40. package/src/mime.d.ts +78 -0
  41. package/src/mime.js +342 -0
  42. package/src/net.d.ts +11 -0
  43. package/src/net.js +29 -2
  44. package/src/pine.js +10 -1
  45. package/src/router.js +3 -3
  46. package/src/sandbox-linux.d.ts +3 -1
  47. package/src/sandbox-linux.js +5 -0
  48. package/src/security.d.ts +22 -6
  49. package/src/security.js +44 -13
  50. package/src/slots.d.ts +106 -0
  51. package/src/slots.js +250 -0
  52. package/src/source-types.d.ts +20 -0
  53. package/src/sources/calendar.d.ts +24 -0
  54. package/src/sources/calendar.js +265 -0
  55. package/src/sources/command.js +109 -4
  56. package/src/sources/discord.d.ts +4 -0
  57. package/src/sources/discord.js +298 -0
  58. package/src/sources/feed.d.ts +19 -0
  59. package/src/sources/feed.js +257 -0
  60. package/src/sources/http.js +154 -103
  61. package/src/sources/mail.d.ts +51 -0
  62. package/src/sources/mail.js +1013 -0
  63. package/src/sources/matrix.d.ts +4 -0
  64. package/src/sources/matrix.js +232 -0
  65. package/src/sources/modbus.d.ts +15 -0
  66. package/src/sources/modbus.js +240 -0
  67. package/src/sources/onvif.d.ts +35 -0
  68. package/src/sources/onvif.js +326 -0
  69. package/src/sources/presence.d.ts +80 -0
  70. package/src/sources/presence.js +480 -0
  71. package/src/sources/serial.d.ts +21 -0
  72. package/src/sources/serial.js +220 -0
  73. package/src/sources/slack.d.ts +16 -0
  74. package/src/sources/slack.js +1062 -0
  75. package/src/sources/smtp.d.ts +4 -0
  76. package/src/sources/smtp.js +360 -0
  77. package/src/sources/stream.d.ts +68 -0
  78. package/src/sources/stream.js +534 -0
  79. package/src/sources/syslog.d.ts +32 -0
  80. package/src/sources/syslog.js +243 -0
  81. package/src/sources/system.d.ts +14 -0
  82. package/src/sources/system.js +236 -0
  83. package/src/sources/system.swift +102 -0
  84. package/src/sources/telegram.js +34 -1
  85. package/src/sources.d.ts +41 -1
  86. package/src/sources.js +147 -24
  87. package/src/tools.d.ts +1 -1
  88. package/src/tools.js +304 -23
  89. package/src/tui/app.d.ts +35 -2
  90. package/src/tui/app.js +306 -43
  91. package/src/tui/levels.d.ts +68 -0
  92. package/src/tui/levels.js +273 -0
  93. package/src/tui/picture.d.ts +17 -1
  94. package/src/tui/picture.js +72 -5
  95. package/src/types.d.ts +3 -0
  96. package/src/update.d.ts +9 -1
  97. package/src/update.js +75 -3
  98. package/src/watching.d.ts +156 -0
  99. package/src/watching.js +609 -4
@@ -0,0 +1,534 @@
1
+ import dns from "node:dns";
2
+ import net from "node:net";
3
+ import { Type } from "typebox";
4
+ import { fetch, ping, WebSocket } from "undici";
5
+ import { isLocalHost, publicOnlyAgent, reachOptions } from "../net.js";
6
+ import { errText, getPath } from "../util.js";
7
+ import { capped, clip, found, pattern, shown } from "../watching.js";
8
+ /**
9
+ * A service that pushes: it is connected to once and then says by itself when something happens,
10
+ * over Server-Sent Events (one long answer to a web request) or over a WebSocket. For what would
11
+ * otherwise have to be asked again and again, and for services whose only way out is such a
12
+ * stream: ntfy, Gotify, Home Assistant, Mastodon, a webhook relay, a ticker.
13
+ *
14
+ * options: { url, kind?, hello?, token?, tokenHeader?, headers?, event?, path?, match?, changed?, perMinute?, local? }
15
+ * kind "sse" or "websocket". Not given: by the address (ws:// and wss:// are a WebSocket)
16
+ * hello for a WebSocket: what is sent after connecting, one message or a list. {{token}} in it is the token
17
+ * event for SSE: only events of this name
18
+ * path for messages in JSON: only this field of each
19
+ * match only messages this regular expression finds; its first group, if it has one, is the value
20
+ * changed report a value only when it differs from the last one
21
+ * perMinute at most this many reports a minute (30 by default); the rest are counted and dropped
22
+ *
23
+ * event "message": { value, event?, id?, previous?, dropped? }
24
+ * event "down": { url, error } after three attempts in a row that did not connect
25
+ * event "up": { url } when it is connected again
26
+ *
27
+ * This file also holds what the types that keep a connection open share (slack, matrix, discord):
28
+ * the loop that connects again, one WebSocket from open to close, and what a status line may say.
29
+ */
30
+ const MAX_PAUSE = 5 * 60_000;
31
+ /** A connection that lasted this long was a working one: the next attempt starts from the short pause again. */
32
+ const SETTLED = 30_000;
33
+ const DOWN_AFTER = 3;
34
+ const MAX_MESSAGE = 256 * 1024;
35
+ /** A stream that says nothing for this long is taken for dead and connected to again. */
36
+ const SILENCE = 5 * 60_000;
37
+ /** How often a WebSocket is pinged, so that a connection that died without a word is noticed by the system. */
38
+ const PING = 45_000;
39
+ export const clock = (ts = Date.now()) => new Date(ts).toTimeString().slice(0, 8);
40
+ /** This computer itself. What runs here is back quickly when it was restarted, so it is asked again quickly. */
41
+ const loopback = (host) => ["localhost", "127.0.0.1", "::1"].includes(host.replace(/^\[|\]$/g, "").toLowerCase());
42
+ /** The first pause before connecting again to a host: a second, or a twentieth of one for this computer. */
43
+ export const firstPause = (host) => (loopback(host) ? 50 : 1000);
44
+ /**
45
+ * What a service said, as a status line may repeat it. A status line is read by agents without
46
+ * the mark that outside content gets, so only a code or a single word is passed on.
47
+ */
48
+ export const word = (v) => {
49
+ const s = String(v ?? "");
50
+ return /^[\w.:-]{1,48}$/.test(s) ? s : `an answer of ${s.length} characters`;
51
+ };
52
+ /** An error pine words itself: what it says may be shown where the sources are listed. */
53
+ export class Plain extends Error {
54
+ }
55
+ /** Why a connection failed, in words that are pine's own or the system's. */
56
+ function why(e) {
57
+ if (e instanceof Plain)
58
+ return e.message;
59
+ const cause = e?.cause ?? e;
60
+ const text = errText(cause);
61
+ if (/resolves to a private address|leads to an address on your own network/.test(text))
62
+ return `the address leads into your own network. If that is meant, set the source up again with "local": true`;
63
+ if (/BODY_TIMEOUT/.test(String(cause?.code)))
64
+ return "nothing came for five minutes";
65
+ if (typeof cause?.code === "string" && /^[A-Z_0-9]{3,40}$/.test(cause.code))
66
+ return cause.code;
67
+ if (e?.name === "TimeoutError" || /timeout/i.test(text))
68
+ return "no answer in time";
69
+ return "the connection failed";
70
+ }
71
+ const pauseFor = (ms, signal) => new Promise((resolve) => {
72
+ if (signal.aborted)
73
+ return resolve();
74
+ const done = () => {
75
+ clearTimeout(t);
76
+ signal.removeEventListener("abort", done);
77
+ resolve();
78
+ };
79
+ const t = setTimeout(done, ms);
80
+ signal.addEventListener("abort", done, { once: true });
81
+ });
82
+ /**
83
+ * Keep a connection: `run` makes one and returns (or throws) when it has ended, and is then
84
+ * called again after a pause that starts short and doubles with every attempt that did not last,
85
+ * up to five minutes. `run` calls `up` once the connection works. The status line says how
86
+ * things stand; with `report` an address that cannot be reached is an event ("down", once, after
87
+ * three attempts in a row) and so is its return ("up").
88
+ */
89
+ export function hold(source, o) {
90
+ const stop = new AbortController();
91
+ source.onStop(() => stop.abort());
92
+ const base = firstPause(o.host);
93
+ let line = "connecting";
94
+ const say = (text) => {
95
+ if (text)
96
+ line = text;
97
+ const more = o.note?.();
98
+ source.status(more ? `${line}. ${more}` : line);
99
+ };
100
+ say();
101
+ void (async () => {
102
+ let pause = base;
103
+ let fails = 0;
104
+ let since = 0;
105
+ while (!stop.signal.aborted) {
106
+ let was = 0;
107
+ let asked;
108
+ let reason = "the connection was closed";
109
+ try {
110
+ await o.run(stop.signal, () => {
111
+ // Said once for a connection, however often its loop reports that it works.
112
+ if (was)
113
+ return;
114
+ was = Date.now();
115
+ if (fails)
116
+ source.log.info(`connected again after ${fails} failed ${fails === 1 ? "attempt" : "attempts"}`);
117
+ fails = 0;
118
+ since = 0;
119
+ say(`connected since ${clock()}`);
120
+ if (o.report && source.kv.get("down")) {
121
+ source.kv.set("down", false);
122
+ source.emit("up", { url: o.report });
123
+ }
124
+ }, (ms) => void (asked = ms));
125
+ }
126
+ catch (e) {
127
+ reason = why(e);
128
+ }
129
+ if (stop.signal.aborted)
130
+ return;
131
+ if (was)
132
+ say(`connecting again since ${clock()}: ${reason}`);
133
+ else {
134
+ // Said once in the log; the status line carries it from here.
135
+ if (!fails)
136
+ source.log.warn("could not connect", reason);
137
+ fails++;
138
+ since ||= Date.now();
139
+ say(`cannot connect since ${clock(since)} (${fails} ${fails === 1 ? "attempt" : "attempts"}): ${reason}`);
140
+ if (o.report && fails === DOWN_AFTER && !source.kv.get("down")) {
141
+ source.kv.set("down", true);
142
+ source.emit("down", { url: o.report, error: reason });
143
+ }
144
+ }
145
+ if (was && Date.now() - was >= SETTLED)
146
+ pause = base;
147
+ // What the service itself asked for (SSE's "retry") counts for a connection that worked, never below a failed one's pause.
148
+ const now = was && asked !== undefined ? Math.max(Math.min(asked, MAX_PAUSE), 10) : pause;
149
+ await pauseFor(now * (0.9 + Math.random() * 0.2), stop.signal);
150
+ if (!was || Date.now() - was < SETTLED)
151
+ pause = Math.min(pause * 2, MAX_PAUSE);
152
+ }
153
+ })();
154
+ return { signal: stop.signal, refresh: () => say() };
155
+ }
156
+ /** Connections that have to stay on the public internet, or none for a host that is local by its name or by the owner's word. */
157
+ export function guardFor(source, host, local, timeoutMs = SILENCE) {
158
+ if (local === true || isLocalHost(host))
159
+ return undefined;
160
+ const guard = publicOnlyAgent(timeoutMs);
161
+ source.onStop(() => guard.close());
162
+ return guard;
163
+ }
164
+ /** Whether a host answers at all, to say more than "it failed" about a WebSocket that did not open. */
165
+ function probe(url, local) {
166
+ return new Promise((resolve) => {
167
+ const host = url.hostname.replace(/^\[|\]$/g, "");
168
+ const port = Number(url.port || (url.protocol === "wss:" || url.protocol === "https:" ? 443 : 80));
169
+ const s = net.connect({ host, port, ...reachOptions(host, local) });
170
+ const done = (text) => {
171
+ s.destroy();
172
+ resolve(text);
173
+ };
174
+ s.setTimeout(5000, () => done("no answer in time"));
175
+ s.once("error", (e) => done(why(e)));
176
+ s.once("connect", () => done("it is there but did not accept the WebSocket: a wrong path, or it wants a token"));
177
+ });
178
+ }
179
+ /**
180
+ * One WebSocket, from open to close. Resolves with the close code once a connection that was
181
+ * open has closed; rejects when it could not be opened. `guard` keeps it on the public internet.
182
+ * A message is handed on as text; text frames and binary ones alike.
183
+ */
184
+ export async function wire(address, o) {
185
+ const url = new URL(address);
186
+ if (o.guard) {
187
+ // The guard refuses when the connection is made. Asked here first, only to be able to say why.
188
+ const host = url.hostname.replace(/^\[|\]$/g, "");
189
+ const found = net.isIP(host) ? [{ address: host }] : await dns.promises.lookup(host, { all: true }).catch(() => []);
190
+ if (found.some((a) => isLocalHost(a.address)))
191
+ throw new Plain(`${url.hostname} leads to an address on your own network. If that is meant, set the source up again with "local": true`);
192
+ }
193
+ return new Promise((resolve, reject) => {
194
+ if (o.signal.aborted)
195
+ return reject(new Plain("stopped"));
196
+ const ws = new WebSocket(url, { ...(o.guard ? { dispatcher: o.guard } : {}), ...(o.headers && Object.keys(o.headers).length ? { headers: o.headers } : {}) });
197
+ ws.binaryType = "arraybuffer";
198
+ let open = false;
199
+ const w = {
200
+ send: (message) => {
201
+ if (ws.readyState === WebSocket.OPEN)
202
+ ws.send(typeof message === "string" ? message : JSON.stringify(message));
203
+ },
204
+ close: (code) => {
205
+ try {
206
+ ws.close(code ?? 1000);
207
+ }
208
+ catch {
209
+ // already closing
210
+ }
211
+ },
212
+ };
213
+ const stop = () => w.close();
214
+ o.signal.addEventListener("abort", stop, { once: true });
215
+ const alive = setInterval(() => {
216
+ try {
217
+ if (ws.readyState === WebSocket.OPEN)
218
+ ping(ws);
219
+ }
220
+ catch {
221
+ // closing
222
+ }
223
+ }, PING);
224
+ alive.unref?.();
225
+ ws.addEventListener("open", () => {
226
+ open = true;
227
+ try {
228
+ o.onOpen?.(w);
229
+ }
230
+ catch (e) {
231
+ reject(e);
232
+ w.close();
233
+ }
234
+ });
235
+ ws.addEventListener("message", (e) => {
236
+ const text = typeof e.data === "string" ? e.data : Buffer.from(e.data).toString("utf8");
237
+ if (text.length > MAX_MESSAGE)
238
+ return;
239
+ try {
240
+ o.onMessage(text, w);
241
+ }
242
+ catch (err) {
243
+ reject(err);
244
+ w.close();
245
+ }
246
+ });
247
+ ws.addEventListener("close", (e) => {
248
+ o.signal.removeEventListener("abort", stop);
249
+ clearInterval(alive);
250
+ if (open)
251
+ return resolve(Number(e.code) || 1006);
252
+ if (o.signal.aborted)
253
+ return reject(new Plain("stopped"));
254
+ void probe(url, !o.guard).then((text) => reject(new Plain(text)));
255
+ });
256
+ });
257
+ }
258
+ /** A regular expression that has a group: what it finds is a value. One without only says which messages count. */
259
+ const hasGroup = (re) => new RegExp(`${re.source}|`).exec("").length > 1;
260
+ /** Headers that carry a secret. Those go into `token`, which is kept out of the configuration. */
261
+ const SECRET_HEADERS = ["authorization", "proxy-authorization", "cookie"];
262
+ const helloList = (hello) => (hello === undefined || hello === null ? [] : Array.isArray(hello) ? hello : [hello]);
263
+ export const type = {
264
+ summary: "a service that pushes over Server-Sent Events or a WebSocket: reports each message it sends. For ntfy, Home Assistant, Mastodon, webhook relays, tickers",
265
+ options: Type.Object({
266
+ url: Type.String({ description: "the address of the stream: https://... for Server-Sent Events, wss://... for a WebSocket (http:// and ws:// for something on the local network)" }),
267
+ kind: Type.Optional(Type.Union([Type.Literal("sse"), Type.Literal("websocket")], { description: '"sse" or "websocket". Leave out: a ws:// or wss:// address is a WebSocket, any other one Server-Sent Events' })),
268
+ hello: Type.Optional(Type.Any({ description: 'for a WebSocket: what to send right after connecting, to log in or to say what is wanted. One message or a list, each a text or a JSON object, e.g. [{"type": "auth", "access_token": "{{token}}"}, {"id": 1, "type": "subscribe_events"}]. Write {{token}} where the token belongs, never the token itself' })),
269
+ token: Type.Optional(Type.String({ description: "an access token or key, if the service wants one. Sent as Authorization: Bearer <token>, and put where hello says {{token}}", secret: true })),
270
+ tokenHeader: Type.Optional(Type.String({ description: 'send the token as this header instead, as it is, e.g. "x-api-key"' })),
271
+ headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "headers to send when connecting. Not for secrets" })),
272
+ event: Type.Optional(Type.String({ description: 'for Server-Sent Events: only events of this name, e.g. "update"' })),
273
+ path: Type.Optional(Type.String({ description: 'for messages in JSON: take only this field of each, e.g. "event.data.new_state.state". A message without it is left out' })),
274
+ match: Type.Optional(Type.String({ description: 'only messages this regular expression finds something in. If it has a group, what the group finds is the value, e.g. "temperature: ([0-9.]+)"' })),
275
+ changed: Type.Optional(Type.Boolean({ description: "true to report a value only when it differs from the last one. For a stream that repeats a state again and again" })),
276
+ perMinute: Type.Optional(Type.Number({ description: "at most this many reports a minute. Default 30; what comes on top is dropped and counted" })),
277
+ local: Type.Optional(Type.Boolean({ description: "true if the address is on your owner's own network under a name that does not say so (ha.lan). Not needed for an IP address, localhost or a .local name" })),
278
+ }, { additionalProperties: false }),
279
+ plan(o) {
280
+ let url;
281
+ try {
282
+ url = new URL(o.url);
283
+ }
284
+ catch {
285
+ throw new Error(`"${o.url}" is not an address. A stream's looks like https://ntfy.sh/mytopic/sse or wss://example.com/socket`);
286
+ }
287
+ if (!["http:", "https:", "ws:", "wss:"].includes(url.protocol))
288
+ throw new Error("the address must start with https://, http://, wss:// or ws://");
289
+ if (url.username || url.password)
290
+ throw new Error('an address with a user name or password in it is not taken: leave it out of the address and name "token" in "ask"');
291
+ const socket = url.protocol === "ws:" || url.protocol === "wss:";
292
+ const kind = o.kind ?? (socket ? "websocket" : "sse");
293
+ if (kind === "sse" && socket)
294
+ throw new Error("Server-Sent Events come from an https:// address; ws:// and wss:// are a WebSocket");
295
+ const localHost = o.local === true || isLocalHost(url.hostname);
296
+ if ((url.protocol === "http:" || url.protocol === "ws:") && !localHost)
297
+ throw new Error(`an address that is not on your own network must be ${socket || kind === "websocket" ? "wss://" : "https://"}: without it the token and everything it sends cross the internet unprotected`);
298
+ if (kind === "sse" && o.hello !== undefined)
299
+ throw new Error('"hello" is for a WebSocket: Server-Sent Events take nothing after connecting. What they need goes into the address or the headers');
300
+ if (kind === "websocket" && o.event)
301
+ throw new Error('"event" is for Server-Sent Events. For a WebSocket, pick with "path" or "match"');
302
+ for (const m of helloList(o.hello))
303
+ if (typeof m !== "string" && (!m || typeof m !== "object"))
304
+ throw new Error('"hello" is one message or a list of messages, each a text or a JSON object');
305
+ if (JSON.stringify(o.hello ?? "").length > 8000)
306
+ throw new Error('"hello" is too long');
307
+ if (o.match)
308
+ pattern(o.match);
309
+ if (o.perMinute !== undefined && !(o.perMinute >= 1 && o.perMinute <= 600))
310
+ throw new Error('"perMinute" is a number from 1 to 600');
311
+ const secret = Object.keys(o.headers ?? {}).filter((h) => SECRET_HEADERS.includes(h.toLowerCase()));
312
+ if (secret.length)
313
+ throw new Error(`the header ${secret.join(", ")} carries a secret: leave it out, name "token" in "ask" and give "tokenHeader": "${secret[0].toLowerCase()}"`);
314
+ if (o.tokenHeader && !/^[A-Za-z0-9-]+$/.test(o.tokenHeader))
315
+ throw new Error('"tokenHeader" is the name of a header, e.g. "x-api-key"');
316
+ const what = [o.event ? `events named ${o.event}` : "", o.path ? `the field ${o.path}` : "", o.match ? `what /${o.match}/ finds` : ""].filter(Boolean).join(", ");
317
+ const hellos = helloList(o.hello).length;
318
+ return {
319
+ options: { ...o, url: url.href, kind },
320
+ does: [
321
+ `stay connected to ${clip(url.href, 160)}${localHost ? " (an address on your own network or this computer)" : ""} ${kind === "sse" ? "and read the events it sends (Server-Sent Events)" : "over a WebSocket"}`,
322
+ ...(hellos ? [`send it ${hellos === 1 ? "one message" : `${hellos} messages`} after connecting: ${clip(JSON.stringify(o.hello), 300)}`] : []),
323
+ `report ${what ? `${what} of ` : ""}each message${o.changed ? " whose value differs from the last one" : ""}, at most ${o.perMinute ?? 30} a minute`,
324
+ ...(o.token ? [`with the token given, sent only to ${url.host}`] : []),
325
+ ],
326
+ opens: true,
327
+ tell: "It reports what the service sends from now on; nothing that was sent before. The sources tool shows whether it is connected.",
328
+ };
329
+ },
330
+ };
331
+ /** What Server-Sent Events are made of: fields line by line, an empty line ends an event. */
332
+ export function sseParser(on, retry) {
333
+ let buffer = "";
334
+ let data = [];
335
+ let size = 0;
336
+ let event = "";
337
+ let id;
338
+ let first = true;
339
+ const line = (l) => {
340
+ if (l === "") {
341
+ // An event larger than any message worth a turn is left out whole, not reported cut in the middle.
342
+ if (data.length && size <= MAX_MESSAGE)
343
+ on({ event: event || "message", data: data.join("\n"), ...(id !== undefined ? { id } : {}) });
344
+ data = [];
345
+ size = 0;
346
+ event = "";
347
+ return;
348
+ }
349
+ if (l[0] === ":")
350
+ return;
351
+ const colon = l.indexOf(":");
352
+ const field = colon < 0 ? l : l.slice(0, colon);
353
+ let value = colon < 0 ? "" : l.slice(colon + 1);
354
+ if (value[0] === " ")
355
+ value = value.slice(1);
356
+ if (field === "data") {
357
+ size += value.length + 1;
358
+ if (size <= MAX_MESSAGE)
359
+ data.push(value);
360
+ }
361
+ else if (field === "event")
362
+ event = value;
363
+ else if (field === "id") {
364
+ if (!value.includes("\0"))
365
+ id = value.slice(0, 500);
366
+ }
367
+ else if (field === "retry" && /^\d+$/.test(value))
368
+ retry(Number(value));
369
+ };
370
+ return (chunk) => {
371
+ buffer += chunk;
372
+ if (first && buffer.length) {
373
+ if (buffer.charCodeAt(0) === 0xfeff)
374
+ buffer = buffer.slice(1);
375
+ first = false;
376
+ }
377
+ for (;;) {
378
+ const m = /\r\n|\n|\r/.exec(buffer);
379
+ // A lone \r at the very end may be the first half of \r\n.
380
+ if (!m || (m[0] === "\r" && m.index === buffer.length - 1))
381
+ break;
382
+ line(buffer.slice(0, m.index));
383
+ buffer = buffer.slice(m.index + m[0].length);
384
+ }
385
+ if (buffer.length > MAX_MESSAGE * 2)
386
+ buffer = "";
387
+ };
388
+ }
389
+ export default function stream(source) {
390
+ const o = source.options;
391
+ if (typeof o.url !== "string")
392
+ throw new Error(`needs "url": the address of the stream`);
393
+ const url = new URL(o.url);
394
+ const kind = o.kind ?? (url.protocol === "ws:" || url.protocol === "wss:" ? "websocket" : "sse");
395
+ const token = typeof o.token === "string" && o.token ? o.token : undefined;
396
+ source.secret(token);
397
+ // Inside a JSON message the token is written the way JSON writes a text.
398
+ const hellos = helloList(o.hello).map((m) => (typeof m === "string" ? { text: m, json: false } : { text: JSON.stringify(m), json: true }));
399
+ const inHello = hellos.some((m) => m.text.includes("{{token}}"));
400
+ if (inHello && !token)
401
+ throw new Error('"hello" says {{token}}, and there is no token. Set the source up again and name "token" in "ask", so that pine asks your owner for it');
402
+ const re = o.match ? pattern(String(o.match)) : undefined;
403
+ const picks = re ? hasGroup(re) : false;
404
+ const cap = capped(Math.max(1, Number(o.perMinute ?? 30)));
405
+ const guard = guardFor(source, url.hostname, o.local);
406
+ const headers = { ...(o.headers ?? {}) };
407
+ // A token that hello hands over is not sent a second time as a header, unless a header was named for it.
408
+ if (token && (o.tokenHeader || !inHello))
409
+ headers[o.tokenHeader ?? "authorization"] = o.tokenHeader ? token : `Bearer ${token}`;
410
+ let lastId;
411
+ /** One message of the service: picked, filtered, compared, counted, and then reported. */
412
+ const take = (text, more = {}) => {
413
+ let value = text;
414
+ try {
415
+ value = JSON.parse(text);
416
+ }
417
+ catch {
418
+ // plain text
419
+ }
420
+ if (o.path) {
421
+ if (typeof value !== "object" || value === null)
422
+ return;
423
+ value = getPath(value, String(o.path));
424
+ if (value === undefined || value === null)
425
+ return;
426
+ }
427
+ if (re) {
428
+ const hit = found(re, typeof value === "string" ? value : JSON.stringify(value));
429
+ if (hit === null)
430
+ return;
431
+ if (picks)
432
+ value = hit;
433
+ }
434
+ let previous;
435
+ if (o.changed === true) {
436
+ const was = source.changed(value);
437
+ if (!was)
438
+ return;
439
+ previous = was.previous;
440
+ }
441
+ if (!cap.ok())
442
+ return;
443
+ const dropped = cap.dropped();
444
+ source.emit("message", { value: shown(value), ...(more.event && more.event !== "message" ? { event: clip(more.event, 100) } : {}), ...(more.id ? { id: clip(more.id, 200) } : {}), ...(previous !== undefined ? { previous: shown(previous) } : {}), ...(dropped ? { dropped } : {}) });
445
+ };
446
+ const sse = async (signal, up, wait) => {
447
+ let at = url;
448
+ for (let hop = 0;; hop++) {
449
+ if (hop > 5)
450
+ throw new Plain("it sends on and on (more than five redirects)");
451
+ const res = await fetch(at, { headers: { accept: "text/event-stream", "cache-control": "no-cache", ...headers, ...(lastId !== undefined ? { "last-event-id": lastId } : {}) }, redirect: "manual", signal, ...(guard ? { dispatcher: guard } : {}) });
452
+ const to = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
453
+ if (to) {
454
+ await res.body?.cancel().catch(() => { });
455
+ const next = new URL(to, at);
456
+ // The owner confirmed one host. Another one is another decision, and must not get the token.
457
+ if (next.host !== url.host || next.protocol !== url.protocol)
458
+ throw new Plain("it sends on to another address, which is not the one that was confirmed. If that is the right one, set the source up with it");
459
+ at = next;
460
+ continue;
461
+ }
462
+ if (!res.ok || !res.body) {
463
+ await res.body?.cancel().catch(() => { });
464
+ throw new Plain(`it answered ${res.status}`);
465
+ }
466
+ if (!/text\/event-stream/i.test(res.headers.get("content-type") ?? "")) {
467
+ await res.body.cancel().catch(() => { });
468
+ throw new Plain('it does not answer with an event stream. If it is a page or a value to look at again and again, that is an "http" source');
469
+ }
470
+ up();
471
+ const feed = sseParser((e) => {
472
+ if (e.id !== undefined)
473
+ lastId = e.id;
474
+ if (o.event && e.event !== o.event)
475
+ return;
476
+ take(e.data, e);
477
+ }, wait);
478
+ const decoder = new TextDecoder();
479
+ const reader = res.body.getReader();
480
+ for (;;) {
481
+ const { done, value } = await reader.read();
482
+ if (done)
483
+ return;
484
+ feed(decoder.decode(value, { stream: true }));
485
+ }
486
+ }
487
+ };
488
+ const socket = async (signal, up) => {
489
+ const ws = new URL(url);
490
+ if (ws.protocol === "https:")
491
+ ws.protocol = "wss:";
492
+ if (ws.protocol === "http:")
493
+ ws.protocol = "ws:";
494
+ await wire(ws, {
495
+ guard,
496
+ headers,
497
+ signal,
498
+ onOpen: (w) => {
499
+ for (const m of hellos)
500
+ w.send(m.text.replaceAll("{{token}}", m.json ? JSON.stringify(token ?? "").slice(1, -1) : (token ?? "")));
501
+ up();
502
+ },
503
+ onMessage: (text) => take(text),
504
+ });
505
+ };
506
+ hold(source, { host: url.hostname, report: o.url, run: kind === "websocket" ? socket : sse });
507
+ }
508
+ /**
509
+ * The address of a service's API when the owner runs one of their own in its place: reached over
510
+ * https, or on this machine. Returned without a slash at the end.
511
+ */
512
+ export function ownServer(raw, usual) {
513
+ if (raw === undefined || raw === null || raw === "")
514
+ return usual;
515
+ let url;
516
+ try {
517
+ url = new URL(String(raw));
518
+ }
519
+ catch {
520
+ throw new Error(`"${raw}" is not an address`);
521
+ }
522
+ if (url.username || url.password)
523
+ throw new Error("an address with a user name or password in it is not taken");
524
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))
525
+ throw new Error("a server of your own in its place must be reached over https, or run on this machine");
526
+ return url.href.replace(/\/+$/, "");
527
+ }
528
+ /** A list an agent may have written as one text with commas: trimmed entries, no empty ones. */
529
+ export const listOf = (v) => (Array.isArray(v) ? v : typeof v === "string" ? v.split(",") : []).map((x) => String(x).trim()).filter(Boolean);
530
+ /** The keyword a text contains, capitals aside. */
531
+ export const keywordIn = (keywords, text) => {
532
+ const lower = text.toLowerCase();
533
+ return keywords.find((k) => lower.includes(k.toLowerCase()));
534
+ };
@@ -0,0 +1,32 @@
1
+ import type { SourceType } from "../source-types.ts";
2
+ import type { SourceApi } from "../sources.ts";
3
+ /**
4
+ * A syslog listener: takes the log lines that routers, firewalls, switches, access points and NAS
5
+ * boxes send when they are told a "remote log server", and reports the ones that matter.
6
+ *
7
+ * options: { port, host?, protocol?, allow?, match?, severity?, perMinute? }
8
+ * protocol "udp" (default), "tcp" or "both"
9
+ * allow only these sender addresses, as prefixes: ["192.168.1.1", "192.168.2."]
10
+ * match only lines in which this regular expression finds something
11
+ * severity the least severe level still reported (default "warning"): emerg, alert, crit,
12
+ * err, warning, notice, info, debug
13
+ * perMinute at most this many reports a minute (default 20); the rest is counted and dropped
14
+ *
15
+ * event "line": { host, app?, severity, facility, message, from, time?, dropped? }
16
+ *
17
+ * Syslog has no login: whoever can reach the port can write a line, under any host name. `from`
18
+ * is the address a line really came from; `host` is what the line says about itself.
19
+ */
20
+ export declare const SEVERITIES: string[];
21
+ export interface LogLine {
22
+ host?: string;
23
+ app?: string;
24
+ severity: string;
25
+ facility: string;
26
+ message: string;
27
+ time?: string;
28
+ }
29
+ /** Read one syslog line: the newer format (RFC 5424), the older one (RFC 3164), or whatever else it is. */
30
+ export declare function parseLine(raw: string): LogLine;
31
+ export declare const type: SourceType;
32
+ export default function syslog(source: SourceApi): Promise<void>;