@zukhruf/pipes 0.0.0-stage → 0.8.19
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/LICENSE +21 -0
- package/README.md +244 -2
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/pipe-address.d.ts +13 -0
- package/dist/pipe-address.d.ts.map +1 -0
- package/dist/pipe-address.js +24 -0
- package/dist/pipe-address.js.map +1 -0
- package/dist/pipe-endpoint.d.ts +17 -0
- package/dist/pipe-endpoint.d.ts.map +1 -0
- package/dist/pipe-endpoint.js +107 -0
- package/dist/pipe-endpoint.js.map +1 -0
- package/dist/pipe-server.d.ts +26 -0
- package/dist/pipe-server.d.ts.map +1 -0
- package/dist/pipe-server.js +40 -0
- package/dist/pipe-server.js.map +1 -0
- package/dist/unsafe-folder-error.d.ts +7 -0
- package/dist/unsafe-folder-error.d.ts.map +1 -0
- package/dist/unsafe-folder-error.js +11 -0
- package/dist/unsafe-folder-error.js.map +1 -0
- package/package.json +44 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ezzabuzaid
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,245 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @zukhruf/pipes
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Design for review: no code yet.
|
|
4
|
+
|
|
5
|
+
Open:
|
|
6
|
+
|
|
7
|
+
- The per-user rule on Windows. `node:net` cannot set the security of a named pipe, and cannot read the owner of a pipe that it connects to. .NET does both for `PipeOptions.CurrentUserOnly`. By the Windows docs, the default security of a pipe gives every user read access [inference, not run]. Its proof is backlog #4340, and nothing waits for it.
|
|
8
|
+
- A rooted name that only this user may use. A name that is not rooted goes into a folder of this user ([ADR 0002](./docs/adr/0002-the-default-folder-belongs-to-one-user.md)). A rooted name goes into the caller's folder, and this package does not check that folder. No consumer needs the check today. tmux's checks on the caller's folder could be the rule when one does.
|
|
9
|
+
|
|
10
|
+
One program of a computer listens, and other programs of the same computer connect to it. `node:net` does this with a Unix domain socket on macOS and Linux, and with a named pipe on Windows. Each program that does it must answer the same questions. Where is the socket file? Is its path short enough? What if a crashed server left its file? Can another user connect? Which name does the pipe get on Windows? This package answers them once. Its model is .NET's `System.IO.Pipes`: one name gives a pipe on Windows and a socket file elsewhere. libuv calls both kinds a pipe too (`uv_pipe_t`).
|
|
11
|
+
|
|
12
|
+
The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md). The research named here is in the pool map, `.scratch/one-pool-for-the-computer/` at the workspace root, which git does not track.
|
|
13
|
+
|
|
14
|
+
## Use it
|
|
15
|
+
|
|
16
|
+
This project is an experiment. It uses only `node:net`, `node:fs` and `node:crypto`.
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm install @zukhruf/pipes
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { PipeEndpoint } from '@zukhruf/pipes';
|
|
24
|
+
|
|
25
|
+
const endpoint = new PipeEndpoint('greeter', { prefix: 'example' });
|
|
26
|
+
|
|
27
|
+
await using server = await endpoint.listen((socket) => {
|
|
28
|
+
socket.end('hello\n');
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
const socket = await endpoint.address.connect();
|
|
32
|
+
for await (const chunk of socket) console.log(String(chunk).trim());
|
|
33
|
+
console.log(server.endpoint.address.path);
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Output on macOS and Linux, for the user with the id 501:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
hello
|
|
40
|
+
/tmp/example-501/greeter
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Output on Windows:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
hello
|
|
47
|
+
\\.\pipe\example-greeter
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## The API
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import type { Socket } from 'node:net';
|
|
54
|
+
|
|
55
|
+
/** An endpoint that this program owns: it may listen on it. Made from a name (a rooted name is the full path; any other name goes into /tmp/<prefix>-<uid>). */
|
|
56
|
+
export class PipeEndpoint {
|
|
57
|
+
constructor(name: string, options: PipeEndpointOptions);
|
|
58
|
+
/** Where other programs connect; publish `address.path` for them. */
|
|
59
|
+
readonly address: PipeAddress;
|
|
60
|
+
/** Removes the file at the path (ADR 0003), listens, and resolves when listening. */
|
|
61
|
+
listen(connectionListener: (socket: Socket) => void): Promise<PipeServer>;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Where to connect: the path of a pipe on this system, as a program published it. Go's net.UnixAddr. */
|
|
65
|
+
export class PipeAddress {
|
|
66
|
+
constructor(path: string); // checks nothing and makes nothing
|
|
67
|
+
/** The path that `node:net` connects to: a socket path on macOS and Linux, a pipe path on Windows. */
|
|
68
|
+
readonly path: string;
|
|
69
|
+
/** Tries once (ADR 0006). Resolves when the socket is connected. */
|
|
70
|
+
connect(options?: { signal?: AbortSignal }): Promise<Socket>;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export interface PipeEndpointOptions {
|
|
74
|
+
/** Names the default folder, `/tmp/<prefix>-<uid>`, and starts each pipe name on Windows. */
|
|
75
|
+
prefix: string;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** The owner of the socket file while it listens on the path of one endpoint. */
|
|
79
|
+
export class PipeServer implements AsyncDisposable {
|
|
80
|
+
readonly endpoint: PipeEndpoint;
|
|
81
|
+
/** Lets the program exit while the server listens, as net.Server#unref. */
|
|
82
|
+
unref(): this;
|
|
83
|
+
/** Stops listening; Node removes the socket file at the path. Resolves when closed. Connections that are open stay open (Node's rule); the caller ends them. A call after the first closes nothing more, as .NET's Dispose ignores the calls after the first: it waits for the same close and resolves. */
|
|
84
|
+
close(): Promise<void>;
|
|
85
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export class UnsafeFolderError extends Error {
|
|
89
|
+
/** The default folder. */
|
|
90
|
+
readonly path: string;
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## The rules
|
|
95
|
+
|
|
96
|
+
- A name is rooted or plain. A rooted name is an absolute path (`path.isAbsolute`). A plain name is one file name: not empty, not `.` or `..`, with no `/`, no `\`, and no zero byte. This is .NET's rule: "Caller is in full control of file location" for a rooted name, and the default folder for any other name ([ADR 0001](./docs/adr/0001-the-scope-and-the-name-of-dotnet-system-io-pipes.md)).
|
|
97
|
+
- On macOS and Linux, a rooted name is the socket path as it is. A plain name is the file `<name>` in the default folder, `/tmp/<prefix>-<uid>`. `<uid>` is `process.getuid()`.
|
|
98
|
+
- On Windows, a plain name is the pipe `\\.\pipe\<prefix>-<name>`. A rooted name is the pipe `\\.\pipe\<prefix>-<id>`, where `<id>` is the first 32 hex digits of the SHA-256 of the resolved path in lower case. Pipe names are one namespace for the computer, and Windows paths ignore case, so two programs that give the same path meet at one pipe ([ADR 0005](./docs/adr/0005-a-rooted-name-on-windows-is-a-pipe-named-by-a-hash-of-its-path.md)).
|
|
99
|
+
- `prefix` follows the rule of a plain name. It takes the place of .NET's fixed prefix `CoreFxPipe_`: each consumer gives its own, so two consumers never share a folder or a pipe.
|
|
100
|
+
- An endpoint is a value that this program owns: it holds its address and nothing else. An address is a value too: it holds a path. Two addresses with one path are one pipe. The endpoint listens, the address connects, and the server owns the socket file. A program cannot listen on another program's path, because an address has no `listen` ([ADR 0007](./docs/adr/0007-the-endpoint-listens-the-address-connects-and-the-server-owns-its-file.md)).
|
|
101
|
+
- `new PipeEndpoint` reads no file and makes no file. It throws a `RangeError` when the socket path is too long: more than 103 bytes on macOS and 107 bytes on Linux, in UTF-8, of the path as it is given. These are .NET's and Go's limits: one byte less than `sun_path` ([ADR 0004](./docs/adr/0004-the-socket-path-is-at-most-one-byte-less-than-sun-path.md)).
|
|
102
|
+
- `new PipeAddress(path)` takes a path that a program made and published, for example in a row of a table. It reads no file, makes no file and checks no length: the program that made the path checked it. Programs need not agree on the default folder.
|
|
103
|
+
- `endpoint.listen` with a plain name makes the default folder with mode `0700` when it is missing. Then it reads the folder with `lstat`. It throws `UnsafeFolderError` when the folder is not a folder (a link is not a folder), when its owner is another user, or when its group or others have any access. These are tmux's checks for `/tmp/tmux-<uid>`, and the group too ([ADR 0002](./docs/adr/0002-the-default-folder-belongs-to-one-user.md)).
|
|
104
|
+
- `endpoint.listen` with a rooted name does not make the folder. The caller's folder must exist.
|
|
105
|
+
- On macOS and Linux, `endpoint.listen` removes the file at the socket path before it listens, without a check, as .NET's pipe server, Docker and containerd do. So give a path that only one server listens on at a time: an election proves it for `@zukhruf/mutex` and `@zukhruf/single-flight`, and a random name for `@zukhruf/sqlite-notify` ([ADR 0003](./docs/adr/0003-listen-removes-the-file-at-the-path-and-close-removes-it-again.md)).
|
|
106
|
+
- The server owns the socket file while it listens. `server.close()` stops listening at once, and Node removes the socket file. Node removes the file at the path, also when another server's file is there now (probe, 2026-11-14). So a server that lost its right to the path closes before the next server listens. `await using` closes it too: `[Symbol.asyncDispose]` is `close`.
|
|
107
|
+
- Only the first `server.close()` or `[Symbol.asyncDispose]()` closes. A later call, also one made while the first waits for open connections, waits until the server has closed and resolves. Node calls the callback of `close` at the `close` event, and passes `ERR_SERVER_NOT_RUNNING` only "if the server was not open when it was closed" (Node's docs), so the package takes that code as the close that came first. Node never fails the close of a server that listens. This is .NET's rule for `IDisposable.Dispose`: "If an object's Dispose method is called more than once, the object must ignore all calls after the first one" ([learn.microsoft.com](https://learn.microsoft.com/en-us/dotnet/api/system.idisposable.dispose)). Node's `net.Server[Symbol.asyncDispose]` resolves on a second call too, but its `close` rejects with `ERR_SERVER_NOT_RUNNING`. Mutex closes its lock server twice: a lost term closes it, and the store's dispose closes it again.
|
|
108
|
+
- `server.close()` does not end the connections that are open. This is Node's rule. The caller keeps them and ends them: mutex destroys them, and single-flight ends each one after what it wrote is sent. Close first, and end them in the same step, so no new connection comes in between.
|
|
109
|
+
- A crash leaves the socket file. A connect to it gives `ECONNREFUSED` (research 20a P1). The next `endpoint.listen` on the path removes it. Windows removes a pipe when its program exits.
|
|
110
|
+
- A socket that Node makes has mode `0755`. Another user cannot connect to it, because a connect needs the write bit (research 20a P5, Linux).
|
|
111
|
+
- `address.connect` connects once. It does not try again, and it does not remove a dead server's file: what a refused connect means is the caller's rule ([ADR 0006](./docs/adr/0006-connect-tries-once.md)).
|
|
112
|
+
- The package waits on no timer, so it takes no clock.
|
|
113
|
+
- The socket is the `net.Socket` of `node:net`. Call `socket.unref()` when it must not keep the program alive, and `server.unref()` for the server.
|
|
114
|
+
|
|
115
|
+
## Errors
|
|
116
|
+
|
|
117
|
+
| Error | When |
|
|
118
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
119
|
+
| `RangeError` | `new PipeEndpoint` makes a socket path longer than the limit. The message: `The socket path <path> is <n> bytes, more than <limit>; choose a shorter folder or name.` .NET throws `ArgumentOutOfRangeException` here. |
|
|
120
|
+
| `TypeError` | A plain name or a prefix that breaks the rule of a plain name. The message names the value and the rule. |
|
|
121
|
+
| `UnsafeFolderError` | `endpoint.listen` with a plain name finds a default folder that is not a folder, is a link, belongs to another user, or gives access to its group or others. `path` is the folder. The message is tmux's: `<path> is not a folder` or `<path> has unsafe permissions`. |
|
|
122
|
+
| The error of Node.js | All other failures, with its `code`. `endpoint.listen`: `EADDRINUSE` when a live pipe has the name on Windows, `EACCES` for a folder that this user cannot write. `address.connect`: `ENOENT` when nothing is at the path, `ECONNREFUSED` for a dead server's file, `EACCES` for another user's socket, `ABORT_ERR` when the signal aborts. |
|
|
123
|
+
|
|
124
|
+
Check a code with `isErrno` of [`@zukhruf/fs`](../fs/README.md#check-the-error-code). A failed `endpoint.listen` closes its `net.Server`, and a failed `address.connect` destroys its socket.
|
|
125
|
+
|
|
126
|
+
## What each call does
|
|
127
|
+
|
|
128
|
+
| Call | macOS and Linux | Windows |
|
|
129
|
+
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
130
|
+
| `new PipeEndpoint(plain name)` | The path `/tmp/<prefix>-<uid>/<name>`. Checks its length. | The path `\\.\pipe\<prefix>-<name>`. |
|
|
131
|
+
| `new PipeEndpoint(rooted name)` | The name is the path. Checks its length. | The path `\\.\pipe\<prefix>-<32 hex digits of the hash of the lowercased resolved path>`. |
|
|
132
|
+
| `new PipeAddress(path)` | The path as it is. Checks nothing. | The path as it is. Checks nothing. |
|
|
133
|
+
| `endpoint.listen`, plain name | Makes the default folder with mode `0700` if it is missing, and checks it. Removes the file at the path. Listens. | Listens. |
|
|
134
|
+
| `endpoint.listen`, rooted name | Removes the file at the path. Listens. | Listens. |
|
|
135
|
+
| `server.close()`, or the end of `await using` | Stops listening. Node removes the file at the path. Open connections stay open. | Windows removes the pipe. Open connections stay open. |
|
|
136
|
+
| The server's program crashes | The file stays. A connect gives `ECONNREFUSED`. | Windows removes the pipe. A connect gives `ENOENT`. |
|
|
137
|
+
| `address.connect()`, nothing listens | `ENOENT` when there is no file, `ECONNREFUSED` when a dead server's file is there. | `ENOENT`. |
|
|
138
|
+
| Another user's program connects | `EACCES`: the socket has mode `0755`, and the default folder has mode `0700` (research 20a P5). | The default security of a pipe gives every user read access [inference, not run; #4340]. |
|
|
139
|
+
|
|
140
|
+
## Who uses it
|
|
141
|
+
|
|
142
|
+
| Consumer | How | Record |
|
|
143
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
|
144
|
+
| `@zukhruf/mutex` | `new PipeEndpoint(resolve(directory, 'lock.sock'), { prefix: 'zukhruf-mutex' })`. The lock server calls `endpoint.listen` when its election wins, and each client calls `endpoint.address.connect`. It replaces `socketPathFor` in `src/lock-stores/socket/socket-store.ts`, the `rm`, `createServer`, `listen` and `once(server, 'listening')` in `lock-server.ts`, and `connect` and `once(socket, 'connect')` in `reach` of `electing-connector.ts`. The lock server keeps its set of connections, and holds a `PipeServer` in place of a `net.Server`. | backlog #2496 |
|
|
145
|
+
| `@zukhruf/single-flight` | The same with `flight.sock` and the prefix `zukhruf-single-flight`. It replaces `src/connection/socket-path.ts`, the same lines in `src/coordinator/flight-server.ts`, and `reach` in `src/connection/electing-connector.ts`. The ledger `docs/copied-from-mutex.md` records it. | backlog #2496 |
|
|
146
|
+
| `@zukhruf/sqlite-notify` | `new PipeEndpoint(<listener id>, { prefix: 'zukhruf-sqlite-notify' })`. The listener id is 16 random bytes in hex. The listener calls `endpoint.listen` and writes `endpoint.address.path` in its row. A sender calls `new PipeAddress(<the path it read>).connect()`, and removes a dead listener's file after a refused connect. | its ADR 0008 |
|
|
147
|
+
|
|
148
|
+
Backlog #2496 holds the transport code that mutex and single-flight copy. This package is its socket-address part: the third consumer, `@zukhruf/sqlite-notify`, needs only that part. JSON lines, the handshake, the connection supervisor and the server shell keep their two copies.
|
|
149
|
+
|
|
150
|
+
### Mutex's code before and after
|
|
151
|
+
|
|
152
|
+
The socket store names the pipe. Before (`socketPathFor` in `socket-store.ts`):
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
if (process.platform === 'win32') {
|
|
156
|
+
const id = hash('sha256', resolve(directory).toLowerCase()).slice(0, 32);
|
|
157
|
+
return `\\\\.\\pipe\\mutex-${id}`;
|
|
158
|
+
}
|
|
159
|
+
const socketPath = join(directory, 'lock.sock');
|
|
160
|
+
if (Buffer.byteLength(socketPath) > SOCKET_PATH_LIMIT)
|
|
161
|
+
throw new RangeError(/* ... */);
|
|
162
|
+
return socketPath;
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
After:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
const endpoint = new PipeEndpoint(resolve(directory, 'lock.sock'), {
|
|
169
|
+
prefix: 'zukhruf-mutex',
|
|
170
|
+
});
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The pipe on Windows becomes `\\.\pipe\zukhruf-mutex-<id>`, with `<id>` from the path of `lock.sock`: pipe names are one namespace for the computer, so the prefix names the package.
|
|
174
|
+
|
|
175
|
+
The lock server starts. Before (`lock-server.ts`):
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
if (process.platform !== 'win32') {
|
|
179
|
+
await rm(socketPath, { force: true });
|
|
180
|
+
}
|
|
181
|
+
const server = createServer(onConnection);
|
|
182
|
+
server.listen(socketPath);
|
|
183
|
+
await once(server, 'listening');
|
|
184
|
+
server.unref();
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
After:
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
const server = (await endpoint.listen(onConnection)).unref();
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
The lock server closes. The order stays: stop listening, drop the connections, wait for the close, then end the term.
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
const closed = this.#server.close();
|
|
197
|
+
for (const socket of this.#connections) socket.destroy();
|
|
198
|
+
await closed;
|
|
199
|
+
await this.#term.resign({ clean });
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
A client reaches the leader. Before (`reach` in `electing-connector.ts`):
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
async function reach(socketPath: string): Promise<Socket | undefined> {
|
|
206
|
+
const socket = connect(socketPath);
|
|
207
|
+
try {
|
|
208
|
+
await once(socket, 'connect');
|
|
209
|
+
return socket;
|
|
210
|
+
} catch {
|
|
211
|
+
socket.destroy();
|
|
212
|
+
return undefined;
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
After:
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
async function reach(endpoint: PipeEndpoint): Promise<Socket | undefined> {
|
|
221
|
+
return endpoint.address.connect().catch(() => undefined);
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## The same concepts in other systems
|
|
226
|
+
|
|
227
|
+
| System | What it does |
|
|
228
|
+
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
229
|
+
| .NET `System.IO.Pipes`: `NamedPipeServerStream`, `NamedPipeClientStream` | The model of this package, with its classes: a server and a client, each `IDisposable`. One name gives `\\.\pipe\<name>` on Windows and `$TMPDIR/CoreFxPipe_<name>` elsewhere; a rooted name is the full path. The server removes a leftover file before it binds, and removes the file at the last dispose. `PipeOptions.CurrentUserOnly` checks the peer's user id on Unix and sets an ACL on Windows (research 21 §1). |
|
|
230
|
+
| .NET `UnixDomainSocketEndPoint` | Counts the path in UTF-8 bytes with its ending zero byte, and throws `ArgumentOutOfRangeException` above `sun_path`: 103 bytes on macOS, 107 on Linux. A value object for an address. `PipeEndpoint` takes its name, its check and its role. |
|
|
231
|
+
| Go `net` | `net.Listen("unix", path)` and `net.Dial("unix", path)`. The same byte limits. A listener removes its file at `Close` by default (`SetUnlinkOnClose`). A leftover file makes the bind fail. No named pipes. |
|
|
232
|
+
| [go-winio](https://github.com/microsoft/go-winio) | `ListenPipe` and `DialPipe` for Windows named pipes: two factory functions, each giving a `net.Listener` or a `net.Conn`. The caller gives the full `\\.\pipe\` path and the security in SDDL. |
|
|
233
|
+
| Docker [`go-connections/sockets`](https://github.com/docker/go-connections) | Removes the file at the path before it listens, without a check, and sets the mode and owner of the socket. Joins `"unix"` and `"npipe"` for HTTP transports. The caller gives the full path. |
|
|
234
|
+
| [libuv](https://github.com/libuv/libuv) `uv_pipe_t` | The handle under `node:net` for both kinds: a Unix socket on macOS and Linux, a named pipe on Windows. Node's docs call both "IPC" and give the same byte limits (`doc/api/net.md`). |
|
|
235
|
+
| tmux | Makes `/tmp/tmux-<uid>` with mode `0700`, and refuses it when it is not a folder, when its owner is another user, or when others have access (`tmux.c:209-229`, tag 3.5a). The default folder has the same checks. |
|
|
236
|
+
|
|
237
|
+
## Documentation
|
|
238
|
+
|
|
239
|
+
- [0001 The scope and the name of .NET's System.IO.Pipes](./docs/adr/0001-the-scope-and-the-name-of-dotnet-system-io-pipes.md)
|
|
240
|
+
- [0002 The default folder belongs to one user](./docs/adr/0002-the-default-folder-belongs-to-one-user.md)
|
|
241
|
+
- [0003 Listen removes the file at the path, and close removes it again](./docs/adr/0003-listen-removes-the-file-at-the-path-and-close-removes-it-again.md)
|
|
242
|
+
- [0004 The socket path is at most one byte less than sun_path](./docs/adr/0004-the-socket-path-is-at-most-one-byte-less-than-sun-path.md)
|
|
243
|
+
- [0005 A rooted name on Windows is a pipe named by a hash of its path](./docs/adr/0005-a-rooted-name-on-windows-is-a-pipe-named-by-a-hash-of-its-path.md)
|
|
244
|
+
- [0006 Connect tries once](./docs/adr/0006-connect-tries-once.md)
|
|
245
|
+
- [0007 The endpoint listens, the address connects, and the server owns its file](./docs/adr/0007-the-endpoint-listens-the-address-connects-and-the-server-owns-its-file.md)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { PipeAddress } from './pipe-address.ts';
|
|
2
|
+
export { PipeEndpoint, type PipeEndpointOptions } from './pipe-endpoint.ts';
|
|
3
|
+
export { PipeServer } from './pipe-server.ts';
|
|
4
|
+
export { UnsafeFolderError } from './unsafe-folder-error.ts';
|
|
5
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type Socket } from 'node:net';
|
|
2
|
+
/** Where to connect: the path of a pipe on this system, as a program published it. Go's net.UnixAddr. */
|
|
3
|
+
export declare class PipeAddress {
|
|
4
|
+
/** The path that `node:net` connects to: a socket path on macOS and Linux, a pipe path on Windows. */
|
|
5
|
+
readonly path: string;
|
|
6
|
+
/** Checks nothing and makes nothing: the program that made the path checked it. */
|
|
7
|
+
constructor(path: string);
|
|
8
|
+
/** Tries once (ADR 0006). Resolves when the socket is connected. */
|
|
9
|
+
connect(options?: {
|
|
10
|
+
signal?: AbortSignal;
|
|
11
|
+
}): Promise<Socket>;
|
|
12
|
+
}
|
|
13
|
+
//# sourceMappingURL=pipe-address.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipe-address.d.ts","sourceRoot":"","sources":["../src/pipe-address.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,UAAU,CAAC;AAEhD,yGAAyG;AACzG,qBAAa,WAAW;IACtB,sGAAsG;IACtG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mFAAmF;gBACvE,IAAI,EAAE,MAAM;IAIxB,oEAAoE;IAC9D,OAAO,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;CAUvE"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { once } from 'node:events';
|
|
2
|
+
import { connect } from 'node:net';
|
|
3
|
+
/** Where to connect: the path of a pipe on this system, as a program published it. Go's net.UnixAddr. */
|
|
4
|
+
export class PipeAddress {
|
|
5
|
+
/** The path that `node:net` connects to: a socket path on macOS and Linux, a pipe path on Windows. */
|
|
6
|
+
path;
|
|
7
|
+
/** Checks nothing and makes nothing: the program that made the path checked it. */
|
|
8
|
+
constructor(path) {
|
|
9
|
+
this.path = path;
|
|
10
|
+
}
|
|
11
|
+
/** Tries once (ADR 0006). Resolves when the socket is connected. */
|
|
12
|
+
async connect(options = {}) {
|
|
13
|
+
const socket = connect({ path: this.path, ...options });
|
|
14
|
+
try {
|
|
15
|
+
await once(socket, 'connect');
|
|
16
|
+
return socket;
|
|
17
|
+
}
|
|
18
|
+
catch (error) {
|
|
19
|
+
socket.destroy();
|
|
20
|
+
throw error;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
//# sourceMappingURL=pipe-address.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipe-address.js","sourceRoot":"","sources":["../src/pipe-address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAe,OAAO,EAAE,MAAM,UAAU,CAAC;AAEhD,yGAAyG;AACzG,MAAM,OAAO,WAAW;IACtB,sGAAsG;IAC7F,IAAI,CAAS;IAEtB,mFAAmF;IACnF,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,OAAO,CAAC,UAAoC,EAAE;QAClD,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { type Socket } from 'node:net';
|
|
2
|
+
import { PipeAddress } from './pipe-address.ts';
|
|
3
|
+
import { PipeServer } from './pipe-server.ts';
|
|
4
|
+
export interface PipeEndpointOptions {
|
|
5
|
+
/** Names the default folder, `/tmp/<prefix>-<uid>`, and starts each pipe name on Windows. */
|
|
6
|
+
prefix: string;
|
|
7
|
+
}
|
|
8
|
+
/** An endpoint that this program owns: it may listen on it. Made from a name (a rooted name is the full path; any other name goes into /tmp/<prefix>-<uid>). */
|
|
9
|
+
export declare class PipeEndpoint {
|
|
10
|
+
#private;
|
|
11
|
+
/** Where other programs connect; publish `address.path` for them. */
|
|
12
|
+
readonly address: PipeAddress;
|
|
13
|
+
constructor(name: string, { prefix }: PipeEndpointOptions);
|
|
14
|
+
/** Removes the file at the path (ADR 0003), listens, and resolves when listening. */
|
|
15
|
+
listen(connectionListener: (socket: Socket) => void): Promise<PipeServer>;
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=pipe-endpoint.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipe-endpoint.d.ts","sourceRoot":"","sources":["../src/pipe-endpoint.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,UAAU,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAC;AAGzD,MAAM,WAAW,mBAAmB;IAClC,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gKAAgK;AAChK,qBAAa,YAAY;;IACvB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;gBAGlB,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,mBAAmB;IAOzD,qFAAqF;IAC/E,MAAM,CACV,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAC3C,OAAO,CAAC,UAAU,CAAC;CAYvB"}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { hash } from 'node:crypto';
|
|
2
|
+
import { once } from 'node:events';
|
|
3
|
+
import { lstat, mkdir, rm } from 'node:fs/promises';
|
|
4
|
+
import { createServer } from 'node:net';
|
|
5
|
+
import { isAbsolute, win32 } from 'node:path';
|
|
6
|
+
import { PipeAddress } from "./pipe-address.js";
|
|
7
|
+
import { PipeServer, ownServer } from "./pipe-server.js";
|
|
8
|
+
import { UnsafeFolderError } from "./unsafe-folder-error.js";
|
|
9
|
+
/** An endpoint that this program owns: it may listen on it. Made from a name (a rooted name is the full path; any other name goes into /tmp/<prefix>-<uid>). */
|
|
10
|
+
export class PipeEndpoint {
|
|
11
|
+
/** Where other programs connect; publish `address.path` for them. */
|
|
12
|
+
address;
|
|
13
|
+
#placement;
|
|
14
|
+
constructor(name, { prefix }) {
|
|
15
|
+
assertPlainName(prefix, 'prefix');
|
|
16
|
+
if (!isAbsolute(name))
|
|
17
|
+
assertPlainName(name, 'name');
|
|
18
|
+
this.#placement = placementOf(name, prefix);
|
|
19
|
+
this.address = new PipeAddress(this.#placement.path);
|
|
20
|
+
}
|
|
21
|
+
/** Removes the file at the path (ADR 0003), listens, and resolves when listening. */
|
|
22
|
+
async listen(connectionListener) {
|
|
23
|
+
await this.#placement.prepare();
|
|
24
|
+
const server = createServer(connectionListener);
|
|
25
|
+
try {
|
|
26
|
+
server.listen(this.address.path);
|
|
27
|
+
await once(server, 'listening');
|
|
28
|
+
}
|
|
29
|
+
catch (error) {
|
|
30
|
+
server.close();
|
|
31
|
+
throw error;
|
|
32
|
+
}
|
|
33
|
+
return PipeServer[ownServer](this, server);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
function placementOf(name, prefix) {
|
|
37
|
+
if (process.platform === 'win32')
|
|
38
|
+
return new WindowsPipe(name, prefix);
|
|
39
|
+
if (isAbsolute(name))
|
|
40
|
+
return new RootedSocket(name);
|
|
41
|
+
return new DefaultFolderSocket(name, prefix);
|
|
42
|
+
}
|
|
43
|
+
/** A named pipe; Windows removes it when its program exits, so nothing is left to remove (ADR 0005). */
|
|
44
|
+
class WindowsPipe {
|
|
45
|
+
path;
|
|
46
|
+
constructor(name, prefix) {
|
|
47
|
+
const id = isAbsolute(name)
|
|
48
|
+
? hash('sha256', win32.resolve(name).toLowerCase()).slice(0, 32)
|
|
49
|
+
: name;
|
|
50
|
+
this.path = `\\\\.\\pipe\\${prefix}-${id}`;
|
|
51
|
+
}
|
|
52
|
+
async prepare() { }
|
|
53
|
+
}
|
|
54
|
+
/** The socket path is the rooted name as it is, in the caller's folder. */
|
|
55
|
+
class RootedSocket {
|
|
56
|
+
path;
|
|
57
|
+
constructor(path) {
|
|
58
|
+
this.path = checkedSocketPath(path);
|
|
59
|
+
}
|
|
60
|
+
prepare() {
|
|
61
|
+
return rm(this.path, { force: true });
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/** The file `<name>` in `/tmp/<prefix>-<uid>`, a folder of this user only (ADR 0002). */
|
|
65
|
+
class DefaultFolderSocket {
|
|
66
|
+
path;
|
|
67
|
+
#folder;
|
|
68
|
+
#uid;
|
|
69
|
+
constructor(name, prefix) {
|
|
70
|
+
this.#uid = process.getuid();
|
|
71
|
+
this.#folder = `/tmp/${prefix}-${this.#uid}`;
|
|
72
|
+
this.path = checkedSocketPath(`${this.#folder}/${name}`);
|
|
73
|
+
}
|
|
74
|
+
async prepare() {
|
|
75
|
+
await mkdir(this.#folder, { mode: 0o700 }).catch((error) => {
|
|
76
|
+
if (Reflect.get(Object(error), 'code') !== 'EEXIST')
|
|
77
|
+
throw error;
|
|
78
|
+
});
|
|
79
|
+
const folder = await lstat(this.#folder);
|
|
80
|
+
if (!folder.isDirectory()) {
|
|
81
|
+
throw new UnsafeFolderError(this.#folder, 'is not a folder');
|
|
82
|
+
}
|
|
83
|
+
if (folder.uid !== this.#uid || (folder.mode & 0o077) !== 0) {
|
|
84
|
+
throw new UnsafeFolderError(this.#folder, 'has unsafe permissions');
|
|
85
|
+
}
|
|
86
|
+
await rm(this.path, { force: true });
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
/** One byte less than `sun_path`, for its ending zero byte, as .NET and Go (ADR 0004). */
|
|
90
|
+
const SOCKET_PATH_LIMIT = process.platform === 'linux' ? 107 : 103;
|
|
91
|
+
function checkedSocketPath(path) {
|
|
92
|
+
const bytes = Buffer.byteLength(path);
|
|
93
|
+
if (bytes > SOCKET_PATH_LIMIT) {
|
|
94
|
+
throw new RangeError(`The socket path ${path} is ${bytes} bytes, more than ${SOCKET_PATH_LIMIT}; choose a shorter folder or name.`);
|
|
95
|
+
}
|
|
96
|
+
return path;
|
|
97
|
+
}
|
|
98
|
+
/** One file name: not empty, not `.` or `..`, with no `/`, no `\`, and no zero byte. */
|
|
99
|
+
function assertPlainName(value, role) {
|
|
100
|
+
if (value === '' ||
|
|
101
|
+
value === '.' ||
|
|
102
|
+
value === '..' ||
|
|
103
|
+
/[/\\\0]/.test(value)) {
|
|
104
|
+
throw new TypeError(`The ${role} ${JSON.stringify(value)} is not one file name: it must not be empty, "." or "..", and must have no "/", no "\\" and no zero byte.`);
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
//# sourceMappingURL=pipe-endpoint.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipe-endpoint.js","sourceRoot":"","sources":["../src/pipe-endpoint.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { Server } from 'node:net';
|
|
2
|
+
import type { PipeEndpoint } from './pipe-endpoint.ts';
|
|
3
|
+
/** The key of the one call that makes a `PipeServer`. `PipeEndpoint#listen` calls it; the package index does not export it. */
|
|
4
|
+
export declare const ownServer: unique symbol;
|
|
5
|
+
/** The owner of the socket file while it listens on the path of one endpoint. */
|
|
6
|
+
export declare class PipeServer implements AsyncDisposable {
|
|
7
|
+
#private;
|
|
8
|
+
readonly endpoint: PipeEndpoint;
|
|
9
|
+
private constructor();
|
|
10
|
+
/** Owns a `net.Server` that listens on the path of `endpoint`. */
|
|
11
|
+
static [ownServer](endpoint: PipeEndpoint, server: Server): PipeServer;
|
|
12
|
+
/** Lets the program exit while the server listens, as net.Server#unref. */
|
|
13
|
+
unref(): this;
|
|
14
|
+
/**
|
|
15
|
+
* Stops listening; Node removes the socket file at the path. Resolves when
|
|
16
|
+
* closed. Connections that are open stay open (Node's rule); the caller ends
|
|
17
|
+
* them. A call after the first closes nothing more, as .NET's Dispose
|
|
18
|
+
* ignores the calls after the first: it waits for the same close and
|
|
19
|
+
* resolves. Node calls back at the `close` event, with
|
|
20
|
+
* `ERR_SERVER_NOT_RUNNING` only when an earlier call already closed the
|
|
21
|
+
* server.
|
|
22
|
+
*/
|
|
23
|
+
close(): Promise<void>;
|
|
24
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
25
|
+
}
|
|
26
|
+
//# sourceMappingURL=pipe-server.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipe-server.d.ts","sourceRoot":"","sources":["../src/pipe-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,+HAA+H;AAC/H,eAAO,MAAM,SAAS,eAA2B,CAAC;AAElD,iFAAiF;AACjF,qBAAa,UAAW,YAAW,eAAe;;IAChD,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAGhC,OAAO;IAKP,kEAAkE;IAClE,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAItE,2EAA2E;IAC3E,KAAK,IAAI,IAAI;IAKb;;;;;;;;OAQG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvC"}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/** The key of the one call that makes a `PipeServer`. `PipeEndpoint#listen` calls it; the package index does not export it. */
|
|
2
|
+
export const ownServer = Symbol('PipeServer.own');
|
|
3
|
+
/** The owner of the socket file while it listens on the path of one endpoint. */
|
|
4
|
+
export class PipeServer {
|
|
5
|
+
endpoint;
|
|
6
|
+
#server;
|
|
7
|
+
constructor(endpoint, server) {
|
|
8
|
+
this.endpoint = endpoint;
|
|
9
|
+
this.#server = server;
|
|
10
|
+
}
|
|
11
|
+
/** Owns a `net.Server` that listens on the path of `endpoint`. */
|
|
12
|
+
static [ownServer](endpoint, server) {
|
|
13
|
+
return new PipeServer(endpoint, server);
|
|
14
|
+
}
|
|
15
|
+
/** Lets the program exit while the server listens, as net.Server#unref. */
|
|
16
|
+
unref() {
|
|
17
|
+
this.#server.unref();
|
|
18
|
+
return this;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Stops listening; Node removes the socket file at the path. Resolves when
|
|
22
|
+
* closed. Connections that are open stay open (Node's rule); the caller ends
|
|
23
|
+
* them. A call after the first closes nothing more, as .NET's Dispose
|
|
24
|
+
* ignores the calls after the first: it waits for the same close and
|
|
25
|
+
* resolves. Node calls back at the `close` event, with
|
|
26
|
+
* `ERR_SERVER_NOT_RUNNING` only when an earlier call already closed the
|
|
27
|
+
* server.
|
|
28
|
+
*/
|
|
29
|
+
close() {
|
|
30
|
+
return new Promise((resolve, reject) => {
|
|
31
|
+
this.#server.close((error) => error && Reflect.get(error, 'code') !== 'ERR_SERVER_NOT_RUNNING'
|
|
32
|
+
? reject(error)
|
|
33
|
+
: resolve());
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
[Symbol.asyncDispose]() {
|
|
37
|
+
return this.close();
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
//# sourceMappingURL=pipe-server.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pipe-server.js","sourceRoot":"","sources":["../src/pipe-server.ts"],"names":[],"mappings":"AAIA,+HAA+H;AAC/H,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAElD,iFAAiF;AACjF,MAAM,OAAO,UAAU;IACZ,QAAQ,CAAe;IACvB,OAAO,CAAS;IAEzB,YAAoB,QAAsB,EAAE,MAAc;QACxD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,kEAAkE;IAClE,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,QAAsB,EAAE,MAAc;QACvD,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,2EAA2E;IAC3E,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK;QACH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAC3B,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,wBAAwB;gBAC9D,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBACf,CAAC,CAAC,OAAO,EAAE,CACd,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,CAAC,MAAM,CAAC,YAAY,CAAC;QACnB,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF"}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** The default folder is not a folder, is a link, belongs to another user, or gives access to its group or others. */
|
|
2
|
+
export declare class UnsafeFolderError extends Error {
|
|
3
|
+
/** The default folder. */
|
|
4
|
+
readonly path: string;
|
|
5
|
+
constructor(path: string, problem: 'is not a folder' | 'has unsafe permissions');
|
|
6
|
+
}
|
|
7
|
+
//# sourceMappingURL=unsafe-folder-error.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"unsafe-folder-error.d.ts","sourceRoot":"","sources":["../src/unsafe-folder-error.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,GAAG,wBAAwB;CAMxD"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** The default folder is not a folder, is a link, belongs to another user, or gives access to its group or others. */
|
|
2
|
+
export class UnsafeFolderError extends Error {
|
|
3
|
+
/** The default folder. */
|
|
4
|
+
path;
|
|
5
|
+
constructor(path, problem) {
|
|
6
|
+
super(`${path} ${problem}`);
|
|
7
|
+
this.name = 'UnsafeFolderError';
|
|
8
|
+
this.path = path;
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
//# sourceMappingURL=unsafe-folder-error.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"unsafe-folder-error.js","sourceRoot":"","sources":["../src/unsafe-folder-error.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,0BAA0B;IACjB,IAAI,CAAS;IAEtB,YACE,IAAY,EACZ,OAAqD;QAErD,KAAK,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/pipes",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.8.19",
|
|
4
|
+
"description": "One name gives a pipe that one program listens on and other programs of the computer connect to: a Unix socket in a folder of this user on macOS and Linux, a named pipe on Windows. After .NET's `System.IO.Pipes`, on `node:net`.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "https://github.com/JanuaryLabs/zukhruf",
|
|
9
|
+
"directory": "packages/pipes"
|
|
10
|
+
},
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/JanuaryLabs/zukhruf/issues"
|
|
13
|
+
},
|
|
14
|
+
"homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/pipes#readme",
|
|
15
|
+
"keywords": [
|
|
16
|
+
"pipe",
|
|
17
|
+
"named-pipe",
|
|
18
|
+
"unix-socket",
|
|
19
|
+
"unix-domain-socket",
|
|
20
|
+
"ipc",
|
|
21
|
+
"net",
|
|
22
|
+
"windows"
|
|
23
|
+
],
|
|
24
|
+
"type": "module",
|
|
25
|
+
"exports": {
|
|
26
|
+
"./package.json": "./package.json",
|
|
27
|
+
".": {
|
|
28
|
+
"@zukhruf/source": "./src/index.ts",
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"import": "./dist/index.js",
|
|
31
|
+
"default": "./dist/index.js"
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
"files": [
|
|
35
|
+
"dist",
|
|
36
|
+
"!dist/spec/**",
|
|
37
|
+
"!**/*.tsbuildinfo",
|
|
38
|
+
"!**/*.test.*"
|
|
39
|
+
],
|
|
40
|
+
"publishConfig": {
|
|
41
|
+
"access": "public"
|
|
42
|
+
},
|
|
43
|
+
"devDependencies": {
|
|
44
|
+
"@zukhruf/testing": "^0.8.19"
|
|
45
|
+
}
|
|
46
|
+
}
|