@kawaz/sockat 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README-ja.md +192 -3
- package/README.md +192 -3
- package/dist/bind.d.ts +54 -0
- package/dist/bind.js +255 -0
- package/dist/bun.d.ts +25 -0
- package/dist/bun.js +46 -0
- package/dist/bunapi.d.ts +12 -0
- package/dist/bunapi.js +76 -0
- package/dist/config.d.ts +70 -0
- package/dist/config.js +93 -0
- package/dist/connect.d.ts +33 -0
- package/dist/connect.js +260 -0
- package/dist/drive.d.ts +49 -0
- package/dist/drive.js +122 -0
- package/dist/errors.d.ts +62 -0
- package/dist/errors.js +76 -0
- package/dist/fsx.d.ts +87 -0
- package/dist/fsx.js +149 -0
- package/dist/index.d.ts +64 -0
- package/dist/index.js +69 -0
- package/dist/lock.d.ts +28 -0
- package/dist/lock.js +61 -0
- package/dist/names.d.ts +19 -0
- package/dist/names.js +55 -0
- package/dist/netapi.d.ts +12 -0
- package/dist/netapi.js +80 -0
- package/dist/paths.d.ts +46 -0
- package/dist/paths.js +111 -0
- package/dist/resolve.d.ts +7 -0
- package/dist/resolve.js +98 -0
- package/dist/route.d.ts +79 -0
- package/dist/route.js +108 -0
- package/dist/socketfile.d.ts +38 -0
- package/dist/socketfile.js +91 -0
- package/dist/sweep.d.ts +14 -0
- package/dist/sweep.js +172 -0
- package/dist/types.d.ts +100 -0
- package/dist/types.js +1 -0
- package/dist/world.d.ts +198 -0
- package/dist/world.js +666 -0
- package/package.json +36 -5
package/dist/connect.js
ADDED
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import { cwdChangedError, systemError, Unusable } from "./errors.js";
|
|
3
|
+
import { attempt, closeQuietly, entry, fstatId, oPath, procAt, realDir, sameId, statId } from "./fsx.js";
|
|
4
|
+
import { createAt, randomLength } from "./names.js";
|
|
5
|
+
import { below, byteLength, isAbs, joinUnder, relativeTo, splitPath } from "./paths.js";
|
|
6
|
+
import { absTarget, classify, cwdId, lookUpDir, noNative, routeFailure } from "./route.js";
|
|
7
|
+
import {} from "./world.js";
|
|
8
|
+
/**
|
|
9
|
+
* Whether /proc can be used (SPEC "用語"): <proc>/self/fd/<fd> has the
|
|
10
|
+
* (st_dev, st_ino) of the directory the fd holds, for the socket's directory
|
|
11
|
+
* (or / opened for the check when it could not be opened).
|
|
12
|
+
*/
|
|
13
|
+
function procUsable(w, sdir) {
|
|
14
|
+
if (w.cfg.os !== "linux" || w.cfg.proc === "") {
|
|
15
|
+
return false;
|
|
16
|
+
}
|
|
17
|
+
let fd = sdir;
|
|
18
|
+
let opened = false;
|
|
19
|
+
if (fd === null) {
|
|
20
|
+
const r = attempt(() => fs.openSync("/", oPath | fs.constants.O_DIRECTORY));
|
|
21
|
+
if (!r.ok) {
|
|
22
|
+
return false;
|
|
23
|
+
}
|
|
24
|
+
fd = r.value;
|
|
25
|
+
opened = true;
|
|
26
|
+
}
|
|
27
|
+
try {
|
|
28
|
+
const id = fstatId(fd);
|
|
29
|
+
return id !== null && procAt(w.cfg.proc, fd, id) !== null;
|
|
30
|
+
}
|
|
31
|
+
finally {
|
|
32
|
+
if (opened) {
|
|
33
|
+
closeQuietly(fd);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
/** The connect order after standard on this system (the row decided once, by whether /proc can be used). */
|
|
38
|
+
function connectOrder(w, proc) {
|
|
39
|
+
switch (w.cfg.os) {
|
|
40
|
+
case "linux":
|
|
41
|
+
return proc ? ["proc-direct", "thread-cwd-direct", "link-file"] : ["relative", "thread-cwd-direct", "link-file"];
|
|
42
|
+
case "darwin":
|
|
43
|
+
return ["relative", "widened", "thread-cwd-direct", "link-file"];
|
|
44
|
+
case "freebsd":
|
|
45
|
+
return ["at-direct", "link-file"];
|
|
46
|
+
default:
|
|
47
|
+
return ["relative", "link-file"];
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* The spellings of the cwd that the path may start with: what getcwd(3)
|
|
52
|
+
* reports, and $PWD only when it names the cwd (stat($PWD) and stat(".")
|
|
53
|
+
* agree on (st_dev, st_ino)).
|
|
54
|
+
*/
|
|
55
|
+
function cwdSpellings(cwd, id) {
|
|
56
|
+
const out = [cwd];
|
|
57
|
+
const pwd = process.env["PWD"];
|
|
58
|
+
if (pwd !== undefined && isAbs(pwd) && pwd !== cwd) {
|
|
59
|
+
const pid = statId(pwd);
|
|
60
|
+
if (pid !== null && sameId(pid, id)) {
|
|
61
|
+
out.push(pwd);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
return out;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* path (whose directory part is dir) spelt relative to the cwd (SPEC-routes
|
|
68
|
+
* "相対パスの作り方"): below a spelling of the cwd when path starts with one,
|
|
69
|
+
* otherwise (only when that gives nothing short enough) through real paths,
|
|
70
|
+
* climbing out of the cwd with "..". The shorter is kept, and used only when
|
|
71
|
+
* its directory is the absolute one and the cwd did not change meanwhile.
|
|
72
|
+
* Lengths are those of the spelling as the standard is handed it (spell).
|
|
73
|
+
* null when there is no such spelling of at most max bytes.
|
|
74
|
+
*/
|
|
75
|
+
export function newRelative(path, dir, max, spell) {
|
|
76
|
+
const parts = splitPath(path);
|
|
77
|
+
if (!isAbs(path) || parts === null) {
|
|
78
|
+
return null;
|
|
79
|
+
}
|
|
80
|
+
const before = cwdId();
|
|
81
|
+
const cwd = attempt(() => process.cwd());
|
|
82
|
+
if (before === null || !cwd.ok) {
|
|
83
|
+
return null;
|
|
84
|
+
}
|
|
85
|
+
let best = null;
|
|
86
|
+
const keep = (rel) => {
|
|
87
|
+
if (best === null || byteLength(spell(rel)) < byteLength(spell(best))) {
|
|
88
|
+
best = rel;
|
|
89
|
+
}
|
|
90
|
+
};
|
|
91
|
+
for (const prefix of cwdSpellings(cwd.value, before)) {
|
|
92
|
+
const rel = below(path, prefix);
|
|
93
|
+
if (rel !== null) {
|
|
94
|
+
keep(rel);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
const fitsNow = () => best !== null && byteLength(spell(best)) <= max;
|
|
98
|
+
if (!fitsNow()) {
|
|
99
|
+
const real = realDir(dir);
|
|
100
|
+
if (real.ok) {
|
|
101
|
+
const rel = relativeTo(joinUnder(real.value, parts.name), cwd.value);
|
|
102
|
+
if (rel !== null) {
|
|
103
|
+
keep(rel);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
const chosen = best;
|
|
108
|
+
if (chosen === null || byteLength(spell(chosen)) > max) {
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
111
|
+
const relParts = splitPath(chosen);
|
|
112
|
+
if (relParts === null) {
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
const relId = statId(relParts.dir);
|
|
116
|
+
const dirId = statId(dir);
|
|
117
|
+
if (relId === null || dirId === null || !sameId(relId, dirId)) {
|
|
118
|
+
return null;
|
|
119
|
+
}
|
|
120
|
+
const now = cwdId();
|
|
121
|
+
if (now === null || !sameId(now, before)) {
|
|
122
|
+
return null;
|
|
123
|
+
}
|
|
124
|
+
return { spelling: spell(chosen), cwd: before };
|
|
125
|
+
}
|
|
126
|
+
/** What a route does after its connect when it has nothing to do. */
|
|
127
|
+
function nothingAfter() { }
|
|
128
|
+
/** The length of the default connect's link-file spelling <B's real path>/<E>. */
|
|
129
|
+
function linkConnectLen(breal) {
|
|
130
|
+
return byteLength(breal) + 1 + randomLength;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* The B of link-file's connect: Options.base's when given (made here when
|
|
134
|
+
* not there yet; an error making it is the call's), otherwise the process's
|
|
135
|
+
* B of the places 1 to 3 (made here when the process has none yet, and
|
|
136
|
+
* kept). The socket's directory, whose real-path spelling is longer than the
|
|
137
|
+
* path, is no place for it.
|
|
138
|
+
*/
|
|
139
|
+
function connectBase(c) {
|
|
140
|
+
const fits = (_kind, breal) => linkConnectLen(breal) <= c.w.cfg.spellingLength;
|
|
141
|
+
if (c.opts.base !== undefined) {
|
|
142
|
+
return c.w.givenBase(c.opts.base, fits, c.site);
|
|
143
|
+
}
|
|
144
|
+
return c.w.autoBase(false, fits);
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* The connect of path, as the steps the standard takes (see bindSteps): a
|
|
148
|
+
* path the standard takes and an abstract name go to it as they are; a
|
|
149
|
+
* longer one takes the connect order. relative discards a socket connected
|
|
150
|
+
* while the cwd changed (a general error); link-file unlinks its E right
|
|
151
|
+
* after, whatever the outcome.
|
|
152
|
+
*/
|
|
153
|
+
export function* connectSteps(w, path, opts, trace, syscall, spell) {
|
|
154
|
+
const site = { syscall, path };
|
|
155
|
+
const kind = classify(w, path, opts, spell);
|
|
156
|
+
if (kind.kind !== "long") {
|
|
157
|
+
const o = yield kind.spelt;
|
|
158
|
+
trace.route = "standard";
|
|
159
|
+
if (!o.ok) {
|
|
160
|
+
throw o.error;
|
|
161
|
+
}
|
|
162
|
+
return { route: "standard" };
|
|
163
|
+
}
|
|
164
|
+
const dir = lookUpDir(w, path, opts, false, site);
|
|
165
|
+
trace.skip("standard", "path too long");
|
|
166
|
+
let sdir = null;
|
|
167
|
+
if (w.cfg.os === "linux") {
|
|
168
|
+
const r = attempt(() => fs.openSync(dir.dir, oPath | fs.constants.O_DIRECTORY));
|
|
169
|
+
sdir = r.ok ? r.value : null;
|
|
170
|
+
}
|
|
171
|
+
try {
|
|
172
|
+
const c = { w, path, dir, opts, site, sdir };
|
|
173
|
+
for (const route of connectOrder(w, procUsable(w, sdir))) {
|
|
174
|
+
let spelling;
|
|
175
|
+
let after = nothingAfter;
|
|
176
|
+
switch (route) {
|
|
177
|
+
case "proc-direct": {
|
|
178
|
+
if (c.sdir === null) {
|
|
179
|
+
trace.skip(route, "socket directory not opened");
|
|
180
|
+
continue;
|
|
181
|
+
}
|
|
182
|
+
spelling = `${w.cfg.proc}/self/fd/${c.sdir}/${dir.name}`;
|
|
183
|
+
if (byteLength(spelling) > w.cfg.spellingLength) {
|
|
184
|
+
trace.skip(route, "spelling too long");
|
|
185
|
+
continue;
|
|
186
|
+
}
|
|
187
|
+
break;
|
|
188
|
+
}
|
|
189
|
+
case "relative": {
|
|
190
|
+
if (!isAbs(path)) {
|
|
191
|
+
trace.skip(route, "path not absolute");
|
|
192
|
+
continue;
|
|
193
|
+
}
|
|
194
|
+
const rel = newRelative(path, dir.dir, w.cfg.spellingLength, spell);
|
|
195
|
+
if (rel === null) {
|
|
196
|
+
trace.skip(route, "no relative spelling");
|
|
197
|
+
continue;
|
|
198
|
+
}
|
|
199
|
+
spelling = rel.spelling;
|
|
200
|
+
after = (o) => {
|
|
201
|
+
const now = cwdId();
|
|
202
|
+
if (now === null || !sameId(now, rel.cwd)) {
|
|
203
|
+
if (o.ok) {
|
|
204
|
+
o.close();
|
|
205
|
+
}
|
|
206
|
+
trace.route = route;
|
|
207
|
+
throw cwdChangedError();
|
|
208
|
+
}
|
|
209
|
+
};
|
|
210
|
+
break;
|
|
211
|
+
}
|
|
212
|
+
case "link-file": {
|
|
213
|
+
const target = absTarget(path);
|
|
214
|
+
if (target instanceof Unusable) {
|
|
215
|
+
trace.skip(route, target.reason);
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
const b = connectBase(c);
|
|
219
|
+
if (b instanceof Unusable) {
|
|
220
|
+
trace.skip(route, b.reason);
|
|
221
|
+
continue;
|
|
222
|
+
}
|
|
223
|
+
if (linkConnectLen(b.real) > w.cfg.spellingLength) {
|
|
224
|
+
trace.skip(route, "spelling too long");
|
|
225
|
+
continue;
|
|
226
|
+
}
|
|
227
|
+
const made = attempt(() => createAt(w.cfg.random, (n) => fs.symlinkSync(target, entry(b, n))));
|
|
228
|
+
if (!made.ok) {
|
|
229
|
+
trace.skip(route, "E not made");
|
|
230
|
+
continue;
|
|
231
|
+
}
|
|
232
|
+
const name = made.value;
|
|
233
|
+
spelling = joinUnder(b.real, name);
|
|
234
|
+
// A failure to remove E is not reported: a connect that went
|
|
235
|
+
// through is not made a failure by it.
|
|
236
|
+
after = () => {
|
|
237
|
+
attempt(() => fs.unlinkSync(entry(b, name)));
|
|
238
|
+
};
|
|
239
|
+
break;
|
|
240
|
+
}
|
|
241
|
+
default:
|
|
242
|
+
trace.skip(route, noNative);
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
const o = yield spelling;
|
|
246
|
+
after(o);
|
|
247
|
+
trace.route = route;
|
|
248
|
+
if (!o.ok) {
|
|
249
|
+
throw routeFailure(o.error, site, spelling);
|
|
250
|
+
}
|
|
251
|
+
return { route };
|
|
252
|
+
}
|
|
253
|
+
throw systemError("ENAMETOOLONG", syscall, path);
|
|
254
|
+
}
|
|
255
|
+
finally {
|
|
256
|
+
if (sdir !== null) {
|
|
257
|
+
closeQuietly(sdir);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
}
|
package/dist/drive.d.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { type Trace } from "./errors.ts";
|
|
2
|
+
import type { BindResult } from "./bind.ts";
|
|
3
|
+
import { realFile } from "./fsx.ts";
|
|
4
|
+
import type { Outcome } from "./route.ts";
|
|
5
|
+
import { cwdId } from "./route.ts";
|
|
6
|
+
import type { Bound } from "./types.ts";
|
|
7
|
+
/** What the standard did with a spelling: a socket, with how to discard it, or the error. */
|
|
8
|
+
export type Attempted<S> = {
|
|
9
|
+
readonly ok: true;
|
|
10
|
+
readonly socket: S;
|
|
11
|
+
readonly close: () => void;
|
|
12
|
+
} | {
|
|
13
|
+
readonly ok: false;
|
|
14
|
+
readonly error: Error;
|
|
15
|
+
};
|
|
16
|
+
/** Runs steps, handing each spelling to the async standard at. */
|
|
17
|
+
export declare function driveAsync<R, S>(steps: Generator<string, R, Outcome>, at: (spelling: string) => Promise<Attempted<S>>): Promise<{
|
|
18
|
+
result: R;
|
|
19
|
+
socket: S;
|
|
20
|
+
}>;
|
|
21
|
+
/** Runs steps, handing each spelling to the sync standard at. */
|
|
22
|
+
export declare function driveSync<R, S>(steps: Generator<string, R, Outcome>, at: (spelling: string) => Attempted<S>): {
|
|
23
|
+
result: R;
|
|
24
|
+
socket: S;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* What bindEx records before the bind: the socket file at path with its
|
|
28
|
+
* directory resolved to a real path, and the cwd for a relative path (SPEC
|
|
29
|
+
* "remove": the cwd is compared before and after).
|
|
30
|
+
*/
|
|
31
|
+
export interface BeforeBind {
|
|
32
|
+
readonly file: ReturnType<typeof realFile> | null;
|
|
33
|
+
readonly cwd: ReturnType<typeof cwdId>;
|
|
34
|
+
readonly relative: boolean;
|
|
35
|
+
}
|
|
36
|
+
export declare function beforeBind(path: string): BeforeBind;
|
|
37
|
+
/**
|
|
38
|
+
* The Bound of bindEx, the socket file recorded the moment the bind is done
|
|
39
|
+
* (SPEC "remove"): followed to the socket it leads to, the cwd unchanged for
|
|
40
|
+
* a relative path. When it cannot be recorded, a general error is thrown (a
|
|
41
|
+
* remove that could not tell the file must not look like a success), after
|
|
42
|
+
* the E is cleaned up and then the listener discarded: the standard unlinks
|
|
43
|
+
* the spelling on close, which with E gone names nothing, so whatever has
|
|
44
|
+
* replaced the socket file stays. A spelling with no E (a path the standard
|
|
45
|
+
* took as it is) is unlinked by the close all the same.
|
|
46
|
+
*/
|
|
47
|
+
export declare function boundOf<S>(path: string, before: BeforeBind, result: BindResult, socket: S, discard: () => void, trace: Trace): Bound<S>;
|
|
48
|
+
/** Attaches trace's diagnostics to a thrown value. */
|
|
49
|
+
export declare function diagnosed(e: unknown, trace: Trace): Error;
|
package/dist/drive.js
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { asError, withDiagnostics } from "./errors.js";
|
|
2
|
+
import { realFile, sameId, socketAt } from "./fsx.js";
|
|
3
|
+
import { cwdId } from "./route.js";
|
|
4
|
+
import { Cleaner, RecordedSocketFile } from "./socketfile.js";
|
|
5
|
+
function toOutcome(a) {
|
|
6
|
+
return a.ok ? { ok: true, close: a.close } : { ok: false, error: a.error };
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* The standard's answer as an outcome, a throw included (a standard may
|
|
10
|
+
* throw at once rather than fail later: Bun.connect without socket
|
|
11
|
+
* handlers), so the steps always go on and clean up what they made (E, the
|
|
12
|
+
* socket's directory's fd).
|
|
13
|
+
*/
|
|
14
|
+
function thrownAsFailure(e) {
|
|
15
|
+
return { ok: false, error: asError(e) };
|
|
16
|
+
}
|
|
17
|
+
/** Runs steps, handing each spelling to the async standard at. */
|
|
18
|
+
export async function driveAsync(steps, at) {
|
|
19
|
+
let held = null;
|
|
20
|
+
let step = steps.next();
|
|
21
|
+
while (step.done !== true) {
|
|
22
|
+
let a;
|
|
23
|
+
try {
|
|
24
|
+
a = await at(step.value);
|
|
25
|
+
}
|
|
26
|
+
catch (e) {
|
|
27
|
+
a = thrownAsFailure(e);
|
|
28
|
+
}
|
|
29
|
+
held = a.ok ? { socket: a.socket } : null;
|
|
30
|
+
step = steps.next(toOutcome(a));
|
|
31
|
+
}
|
|
32
|
+
if (held === null) {
|
|
33
|
+
throw new Error("sockat: internal error: the steps ended without a socket");
|
|
34
|
+
}
|
|
35
|
+
return { result: step.value, socket: held.socket };
|
|
36
|
+
}
|
|
37
|
+
/** Runs steps, handing each spelling to the sync standard at. */
|
|
38
|
+
export function driveSync(steps, at) {
|
|
39
|
+
let held = null;
|
|
40
|
+
let step = steps.next();
|
|
41
|
+
while (step.done !== true) {
|
|
42
|
+
let a;
|
|
43
|
+
try {
|
|
44
|
+
a = at(step.value);
|
|
45
|
+
}
|
|
46
|
+
catch (e) {
|
|
47
|
+
a = thrownAsFailure(e);
|
|
48
|
+
}
|
|
49
|
+
held = a.ok ? { socket: a.socket } : null;
|
|
50
|
+
step = steps.next(toOutcome(a));
|
|
51
|
+
}
|
|
52
|
+
if (held === null) {
|
|
53
|
+
throw new Error("sockat: internal error: the steps ended without a socket");
|
|
54
|
+
}
|
|
55
|
+
return { result: step.value, socket: held.socket };
|
|
56
|
+
}
|
|
57
|
+
export function beforeBind(path) {
|
|
58
|
+
// A NUL is an abstract name (no file to record) or an argument error,
|
|
59
|
+
// which the bind's own checks throw.
|
|
60
|
+
if (path.includes("\0")) {
|
|
61
|
+
return { file: null, cwd: null, relative: false };
|
|
62
|
+
}
|
|
63
|
+
const relative = !path.startsWith("/");
|
|
64
|
+
return { relative, cwd: relative ? cwdId() : null, file: realFile(path) };
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* The Bound of bindEx, the socket file recorded the moment the bind is done
|
|
68
|
+
* (SPEC "remove"): followed to the socket it leads to, the cwd unchanged for
|
|
69
|
+
* a relative path. When it cannot be recorded, a general error is thrown (a
|
|
70
|
+
* remove that could not tell the file must not look like a success), after
|
|
71
|
+
* the E is cleaned up and then the listener discarded: the standard unlinks
|
|
72
|
+
* the spelling on close, which with E gone names nothing, so whatever has
|
|
73
|
+
* replaced the socket file stays. A spelling with no E (a path the standard
|
|
74
|
+
* took as it is) is unlinked by the close all the same.
|
|
75
|
+
*/
|
|
76
|
+
export function boundOf(path, before, result, socket, discard, trace) {
|
|
77
|
+
const cleaner = new Cleaner(result.link, path);
|
|
78
|
+
let recorded = null;
|
|
79
|
+
if (before.file !== null) {
|
|
80
|
+
let ok = before.file.ok;
|
|
81
|
+
if (before.file.ok) {
|
|
82
|
+
const sock = socketAt(before.file.value);
|
|
83
|
+
ok = sock.ok;
|
|
84
|
+
if (sock.ok) {
|
|
85
|
+
recorded = sock.value;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
if (ok && before.relative) {
|
|
89
|
+
const now = cwdId();
|
|
90
|
+
ok = now !== null && before.cwd !== null && sameId(now, before.cwd);
|
|
91
|
+
}
|
|
92
|
+
if (!ok) {
|
|
93
|
+
let eGone = result.link === null;
|
|
94
|
+
try {
|
|
95
|
+
cleaner.cleanup();
|
|
96
|
+
eGone = true;
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
// The error of the call is that the file could not be recorded.
|
|
100
|
+
}
|
|
101
|
+
discard();
|
|
102
|
+
const left = result.link === null
|
|
103
|
+
? "the listener was closed, which unlinks the path"
|
|
104
|
+
: eGone
|
|
105
|
+
? "the listener was closed and what is at the path left"
|
|
106
|
+
: "the listener was closed, which unlinks the spelling (its symlink could not be removed first)";
|
|
107
|
+
throw withDiagnostics(new Error(`listen ${path}: the socket file bound could not be recorded for its removal; ${left}`), trace);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return {
|
|
111
|
+
socket,
|
|
112
|
+
file: new RecordedSocketFile(recorded, cleaner),
|
|
113
|
+
spelling: result.spelling,
|
|
114
|
+
route: result.route,
|
|
115
|
+
base: result.base,
|
|
116
|
+
skipped: [...trace.skipped],
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
/** Attaches trace's diagnostics to a thrown value. */
|
|
120
|
+
export function diagnosed(e, trace) {
|
|
121
|
+
return withDiagnostics(asError(e), trace);
|
|
122
|
+
}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/** A route found unusable, and why (diagnostics only; not a promise). */
|
|
2
|
+
export interface Skip {
|
|
3
|
+
readonly name: string;
|
|
4
|
+
readonly reason: string;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* A route that cannot be used here, and why (SPEC "使えない"): the order
|
|
8
|
+
* moves on to the next route and records it in `skipped`. Never thrown out
|
|
9
|
+
* of the package.
|
|
10
|
+
*/
|
|
11
|
+
export declare class Unusable {
|
|
12
|
+
readonly reason: string;
|
|
13
|
+
constructor(reason: string);
|
|
14
|
+
}
|
|
15
|
+
/** The call an error belongs to: the system call named in it and the caller's path. */
|
|
16
|
+
export interface CallSite {
|
|
17
|
+
readonly syscall: string;
|
|
18
|
+
readonly path: string;
|
|
19
|
+
}
|
|
20
|
+
/** An OS error as sockat throws it. */
|
|
21
|
+
export interface SystemError extends Error {
|
|
22
|
+
code: string;
|
|
23
|
+
errno: number;
|
|
24
|
+
syscall: string;
|
|
25
|
+
path: string;
|
|
26
|
+
address: string;
|
|
27
|
+
}
|
|
28
|
+
/** The diagnostics the `*Ex` functions and the resolves attach to their errors. */
|
|
29
|
+
export interface RouteDiagnostics {
|
|
30
|
+
/** The route that bound / connected and failed; null when none did. */
|
|
31
|
+
route: string | null;
|
|
32
|
+
/** The routes found unusable before it, in the order tried. */
|
|
33
|
+
skipped: Skip[];
|
|
34
|
+
}
|
|
35
|
+
/** What the routes record of one call: the routes skipped and the route that failed. */
|
|
36
|
+
export declare class Trace {
|
|
37
|
+
readonly skipped: Skip[];
|
|
38
|
+
route: string | null;
|
|
39
|
+
skip(name: string, reason: string): void;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* An OS error of code (an errno's name) from syscall at path, in the shape
|
|
43
|
+
* Node gives the errors of node:net (`listen EACCES: permission denied /p`).
|
|
44
|
+
* `path` and `address` are both the caller's path.
|
|
45
|
+
*/
|
|
46
|
+
export declare function systemError(code: string, syscall: string, path: string, note?: string): SystemError;
|
|
47
|
+
/** An argument error (SPEC "エラー": 引数の誤り). */
|
|
48
|
+
export declare function invalidArgument(name: string, value: string, reason: string): TypeError & {
|
|
49
|
+
code: string;
|
|
50
|
+
};
|
|
51
|
+
/** The general error of a relative connect whose cwd changed meanwhile. */
|
|
52
|
+
export declare function cwdChangedError(): Error;
|
|
53
|
+
/** err with the diagnostics of trace attached. */
|
|
54
|
+
export declare function withDiagnostics<E extends Error>(err: E, trace: Trace): E & RouteDiagnostics;
|
|
55
|
+
/**
|
|
56
|
+
* The errno name of a thrown value or an error event (Node's and Bun's
|
|
57
|
+
* errors carry it as `code`), undefined when it has none. The one place
|
|
58
|
+
* where sockat reads an error it did not make.
|
|
59
|
+
*/
|
|
60
|
+
export declare function errnoCode(e: unknown): string | undefined;
|
|
61
|
+
/** A thrown value as an Error (the runtimes throw Errors; anything else is wrapped). */
|
|
62
|
+
export declare function asError(e: unknown): Error;
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { getSystemErrorMap } from "node:util";
|
|
2
|
+
/**
|
|
3
|
+
* A route that cannot be used here, and why (SPEC "使えない"): the order
|
|
4
|
+
* moves on to the next route and records it in `skipped`. Never thrown out
|
|
5
|
+
* of the package.
|
|
6
|
+
*/
|
|
7
|
+
export class Unusable {
|
|
8
|
+
reason;
|
|
9
|
+
constructor(reason) {
|
|
10
|
+
this.reason = reason;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/** What the routes record of one call: the routes skipped and the route that failed. */
|
|
14
|
+
export class Trace {
|
|
15
|
+
skipped = [];
|
|
16
|
+
route = null;
|
|
17
|
+
skip(name, reason) {
|
|
18
|
+
this.skipped.push({ name, reason });
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
/** The name and message of each errno, by name, from the runtime's table. */
|
|
22
|
+
const errnoByName = (() => {
|
|
23
|
+
const m = new Map();
|
|
24
|
+
for (const [errno, [name, message]] of getSystemErrorMap()) {
|
|
25
|
+
if (!m.has(name)) {
|
|
26
|
+
m.set(name, { errno, message });
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return m;
|
|
30
|
+
})();
|
|
31
|
+
/**
|
|
32
|
+
* An OS error of code (an errno's name) from syscall at path, in the shape
|
|
33
|
+
* Node gives the errors of node:net (`listen EACCES: permission denied /p`).
|
|
34
|
+
* `path` and `address` are both the caller's path.
|
|
35
|
+
*/
|
|
36
|
+
export function systemError(code, syscall, path, note) {
|
|
37
|
+
const known = errnoByName.get(code);
|
|
38
|
+
const head = known === undefined ? `${syscall} ${code} ${path}` : `${syscall} ${code}: ${known.message} ${path}`;
|
|
39
|
+
const message = note === undefined ? head : `${head} (${note})`;
|
|
40
|
+
return Object.assign(new Error(message), {
|
|
41
|
+
code,
|
|
42
|
+
errno: known === undefined ? 0 : known.errno,
|
|
43
|
+
syscall,
|
|
44
|
+
path,
|
|
45
|
+
address: path,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
/** An argument error (SPEC "エラー": 引数の誤り). */
|
|
49
|
+
export function invalidArgument(name, value, reason) {
|
|
50
|
+
return Object.assign(new TypeError(`The argument '${name}' ${reason}. Received ${JSON.stringify(value)}`), {
|
|
51
|
+
code: "ERR_INVALID_ARG_VALUE",
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
/** The general error of a relative connect whose cwd changed meanwhile. */
|
|
55
|
+
export function cwdChangedError() {
|
|
56
|
+
return new Error("The current directory changed while connecting through a path relative to it; the result was discarded");
|
|
57
|
+
}
|
|
58
|
+
/** err with the diagnostics of trace attached. */
|
|
59
|
+
export function withDiagnostics(err, trace) {
|
|
60
|
+
return Object.assign(err, { route: trace.route, skipped: [...trace.skipped] });
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* The errno name of a thrown value or an error event (Node's and Bun's
|
|
64
|
+
* errors carry it as `code`), undefined when it has none. The one place
|
|
65
|
+
* where sockat reads an error it did not make.
|
|
66
|
+
*/
|
|
67
|
+
export function errnoCode(e) {
|
|
68
|
+
if (e instanceof Error && "code" in e && typeof e.code === "string" && /^E[A-Z0-9]+$/.test(e.code)) {
|
|
69
|
+
return e.code;
|
|
70
|
+
}
|
|
71
|
+
return undefined;
|
|
72
|
+
}
|
|
73
|
+
/** A thrown value as an Error (the runtimes throw Errors; anything else is wrapped). */
|
|
74
|
+
export function asError(e) {
|
|
75
|
+
return e instanceof Error ? e : new Error(String(e));
|
|
76
|
+
}
|
package/dist/fsx.d.ts
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
/** (st_dev, st_ino). */
|
|
3
|
+
export interface FileId {
|
|
4
|
+
readonly dev: bigint;
|
|
5
|
+
readonly ino: bigint;
|
|
6
|
+
}
|
|
7
|
+
export declare function sameId(a: FileId, b: FileId): boolean;
|
|
8
|
+
/** The outcome of a file system call: its value, or the errno's name it failed with. */
|
|
9
|
+
export type Result<T> = {
|
|
10
|
+
readonly ok: true;
|
|
11
|
+
readonly value: T;
|
|
12
|
+
} | {
|
|
13
|
+
readonly ok: false;
|
|
14
|
+
readonly code: string;
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* Runs a file system call, turning an error with an errno into a value.
|
|
18
|
+
* An error without one (a bug, not the file system's answer) is thrown.
|
|
19
|
+
*/
|
|
20
|
+
export declare function attempt<T>(f: () => T): Result<T>;
|
|
21
|
+
export declare function lstat(path: string): Result<fs.BigIntStats>;
|
|
22
|
+
export declare function fstat(fd: number): Result<fs.BigIntStats>;
|
|
23
|
+
/** The (st_dev, st_ino) of what path names (following symlinks), null when it cannot be looked up. */
|
|
24
|
+
export declare function statId(path: string): FileId | null;
|
|
25
|
+
export declare function lstatId(path: string): FileId | null;
|
|
26
|
+
export declare function fstatId(fd: number): FileId | null;
|
|
27
|
+
/** The effective uid (B's name and the checks of B, D and their ancestors). */
|
|
28
|
+
export declare function euid(): number;
|
|
29
|
+
/** Whether st is a directory owned by the effective uid. */
|
|
30
|
+
export declare function isOurDir(st: fs.BigIntStats): boolean;
|
|
31
|
+
/** The permission bits of st (mode & 07777). */
|
|
32
|
+
export declare function modeBits(st: fs.BigIntStats): number;
|
|
33
|
+
/**
|
|
34
|
+
* dir as a real path (symlinks resolved, absolute), by realpath(3): the
|
|
35
|
+
* system looks up every component, ".." included, as the kernel does (a
|
|
36
|
+
* "sym/.." is the parent of the symlink's target, not the directory the
|
|
37
|
+
* symlink is in). The path is never folded as a string (SPEC "長いパスの経路と
|
|
38
|
+
* 試す順番": パスを字句で畳まない).
|
|
39
|
+
*/
|
|
40
|
+
export declare function realDir(dir: string): Result<string>;
|
|
41
|
+
/**
|
|
42
|
+
* The socket file at path with its directory resolved to a real path, so a
|
|
43
|
+
* later change of the cwd or of a symlink on the way does not retarget it.
|
|
44
|
+
*/
|
|
45
|
+
export declare function realFile(path: string): Result<string>;
|
|
46
|
+
/**
|
|
47
|
+
* The socket file at file (whose directory is a real path): when its last
|
|
48
|
+
* component is a symlink, followed as bind(2) follows it on the systems
|
|
49
|
+
* where it does (SPEC "remove", "ForBind の SocketFile"), each target taken
|
|
50
|
+
* relative to the directory of its symlink and its directory resolved to a
|
|
51
|
+
* real path. The real path of the socket reached and its (st_dev, st_ino),
|
|
52
|
+
* or the errno: the lstat's (ENOENT, ...), ENOTSOCK when what is reached is
|
|
53
|
+
* not a socket, ELOOP after maxFollow symlinks.
|
|
54
|
+
*/
|
|
55
|
+
export declare function socketAt(file: string): Result<{
|
|
56
|
+
file: string;
|
|
57
|
+
id: FileId;
|
|
58
|
+
}>;
|
|
59
|
+
/** How B and D are opened: for reading (D takes its lock, sweep lists B), never through a symlink. */
|
|
60
|
+
export declare const dirOpenFlags: number;
|
|
61
|
+
/**
|
|
62
|
+
* Linux's O_PATH (not in fs.constants): opens a directory with search
|
|
63
|
+
* permission alone (the socket's directory for proc-direct, the parent of B).
|
|
64
|
+
*/
|
|
65
|
+
export declare const oPath = 2097152;
|
|
66
|
+
/**
|
|
67
|
+
* A directory held by its fd, through which its entries are named: by
|
|
68
|
+
* /proc/self/fd/<fd>/<name> where /proc can be used for it (Linux), so the
|
|
69
|
+
* name is looked up in the directory held, as *at system calls would;
|
|
70
|
+
* otherwise by its real path, every directory on the way to which was
|
|
71
|
+
* checked so that nobody else can replace it (DR-0002).
|
|
72
|
+
*/
|
|
73
|
+
export interface HeldDir {
|
|
74
|
+
/** The directory's real path. */
|
|
75
|
+
readonly real: string;
|
|
76
|
+
/** /proc/self/fd/<fd>, when /proc names the directory held by fd; null otherwise. */
|
|
77
|
+
readonly at: string | null;
|
|
78
|
+
}
|
|
79
|
+
/** The path through which the entry name of dir is reached. */
|
|
80
|
+
export declare function entry(dir: HeldDir, name: string): string;
|
|
81
|
+
/**
|
|
82
|
+
* <proc>/self/fd/<fd>, when proc is set and it names the directory held by
|
|
83
|
+
* fd (the same (st_dev, st_ino) as fd's); null otherwise.
|
|
84
|
+
*/
|
|
85
|
+
export declare function procAt(proc: string, fd: number, id: FileId): string | null;
|
|
86
|
+
/** Closes fd, ignoring an error (an fd of ours closed once). */
|
|
87
|
+
export declare function closeQuietly(fd: number): void;
|