Skip to content

Commit 461b3d4

Browse files
TommyDew42sindresorhusszmarczak
authored
Add enableUnixSockets option (#2062)
Co-authored-by: Sindre Sorhus <[email protected]> Co-authored-by: Szymon Marczak <[email protected]>
1 parent d4c2913 commit 461b3d4

File tree

8 files changed

+97
-19
lines changed

8 files changed

+97
-19
lines changed

‎documentation/2-options.md

+31
Original file line numberDiff line numberDiff line change
@@ -918,6 +918,37 @@ By default, requests will not use [method rewriting](https://datatracker.ietf.or
918918

919919
For example, when sending a `POST` request and receiving a `302`, it will resend the body to the new location using the same HTTP method (`POST` in this case). To rewrite the request as `GET`, set this option to `true`.
920920

921+
### `enableUnixSockets`
922+
923+
**Type: `boolean`**\
924+
**Default: `true`**
925+
926+
When enabled, requests can also be sent via [UNIX Domain Sockets](https://serverfault.com/questions/124517/what-is-the-difference-between-unix-sockets-and-tcp-ip-sockets). Please note that in the upcoming major release (Got v13) this default will be changed to `false` for security reasons.
927+
928+
> **Warning**
929+
> Make sure you do your own URL sanitizing if you accept untrusted user input for the URL.
930+
931+
Use the following URL scheme: `PROTOCOL://unix:SOCKET:PATH`
932+
933+
- `PROTOCOL` - `http` or `https`
934+
- `SOCKET` - Absolute path to a UNIX domain socket, for example: `/var/run/docker.sock`
935+
- `PATH` - Request path, for example: `/v2/keys`
936+
937+
```js
938+
import got from 'got';
939+
940+
await got('http://unix:/var/run/docker.sock:/containers/json', {enableUnixSockets: true});
941+
942+
// Or without protocol (HTTP by default)
943+
await got('unix:/var/run/docker.sock:/containers/json', {enableUnixSockets: true});
944+
945+
// Disable Unix sockets
946+
const gotUnixSocketsDisabled = got.extend({enableUnixSockets: false});
947+
948+
// RequestError: Using UNIX domain sockets but option `enableUnixSockets` is not enabled
949+
await gotUnixSocketsDisabled('http://unix:/var/run/docker.sock:/containers/json');
950+
```
951+
921952
## Methods
922953

923954
### `options.merge(other: Options | OptionsInit)`

‎documentation/migration-guides/axios.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ We deeply care about readability, so we renamed these options:
2424

2525
- `httpAgent` → [`agent.http`](../2-options.md#agent)
2626
- `httpsAgent` → [`agent.https`](../2-options.md#agent)
27-
- `socketPath` → [`url`](../tips.md#unix)
27+
- `socketPath` → [`url`](../2-options.md#enableunixsockets)
2828
- `responseEncoding` → [`encoding`](../2-options.md#encoding)
2929
- `auth.username` → [`username`](../2-options.md#username)
3030
- `auth.password` → [`password`](../2-options.md#password)

‎documentation/migration-guides/request.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ These Got options are the same as with Request:
4646
- [`localAddress`](../2-options.md#localaddress)
4747
- [`headers`](../2-options.md#headers)
4848
- [`createConnection`](../2-options.md#createconnection)
49-
- [UNIX sockets](../tips.md#unixsockets): `http://unix:SOCKET:PATH`
49+
- [UNIX sockets](../2-options.md#enableunixsockets): `http://unix:SOCKET:PATH`
5050

5151
The `time` option does not exist, assume [it's always true](../6-timeout.md).
5252

‎documentation/tips.md

+1-15
Original file line numberDiff line numberDiff line change
@@ -92,21 +92,7 @@ for await (const commitData of pagination) {
9292
<a name="unix"></a>
9393
### UNIX Domain Sockets
9494

95-
Requests can also be sent via [UNIX Domain Sockets](https://serverfault.com/questions/124517/what-is-the-difference-between-unix-sockets-and-tcp-ip-sockets).\
96-
Use the following URL scheme: `PROTOCOL://unix:SOCKET:PATH`
97-
98-
- `PROTOCOL` - `http` or `https`
99-
- `SOCKET` - Absolute path to a unix domain socket, for example: `/var/run/docker.sock`
100-
- `PATH` - Request path, for example: `/v2/keys`
101-
102-
```js
103-
import got from 'got';
104-
105-
await got('http://unix:/var/run/docker.sock:/containers/json');
106-
107-
// Or without protocol (HTTP by default)
108-
await got('unix:/var/run/docker.sock:/containers/json');
109-
```
95+
See the [`enableUnixSockets` option](./2-options.md#enableunixsockets).
11096

11197
### Testing
11298

‎readme.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ For advanced JSON usage, check out the [`parseJson`](documentation/2-options.md#
202202

203203
- [x] [RFC compliant caching](documentation/cache.md)
204204
- [x] [Proxy support](documentation/tips.md#proxying)
205-
- [x] [Unix Domain Sockets](documentation/tips.md#unix)
205+
- [x] [Unix Domain Sockets](documentation/2-options.md#enableunixsockets)
206206

207207
#### Integration
208208

‎source/core/options.ts

+15
Original file line numberDiff line numberDiff line change
@@ -827,6 +827,7 @@ const defaultInternals: Options['_internals'] = {
827827
},
828828
setHost: true,
829829
maxHeaderSize: undefined,
830+
enableUnixSockets: true,
830831
};
831832

832833
const cloneInternals = (internals: typeof defaultInternals) => {
@@ -1428,6 +1429,10 @@ export default class Options {
14281429
}
14291430

14301431
if (url.hostname === 'unix') {
1432+
if (!this._internals.enableUnixSockets) {
1433+
throw new Error('Using UNIX domain sockets but option `enableUnixSockets` is not enabled');
1434+
}
1435+
14311436
const matches = /(?<socketPath>.+?):(?<path>.+)/.exec(`${url.pathname}${url.search}`);
14321437

14331438
if (matches?.groups) {
@@ -2345,6 +2350,16 @@ export default class Options {
23452350
this._internals.maxHeaderSize = value;
23462351
}
23472352

2353+
get enableUnixSockets() {
2354+
return this._internals.enableUnixSockets;
2355+
}
2356+
2357+
set enableUnixSockets(value: boolean) {
2358+
assert.boolean(value);
2359+
2360+
this._internals.enableUnixSockets = value;
2361+
}
2362+
23482363
// eslint-disable-next-line @typescript-eslint/naming-convention
23492364
toJSON() {
23502365
return {...this._internals};

‎test/redirects.ts

+22-1
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,12 @@ const unixHostname: Handler = (_request, response) => {
4242
response.end();
4343
};
4444

45-
test('cannot redirect to unix protocol', withServer, async (t, server, got) => {
45+
test('cannot redirect to UNIX protocol when UNIX sockets are enabled', withServer, async (t, server, got) => {
4646
server.get('/protocol', unixProtocol);
4747
server.get('/hostname', unixHostname);
4848

49+
t.true(got.defaults.options.enableUnixSockets);
50+
4951
await t.throwsAsync(got('protocol'), {
5052
message: 'Cannot redirect to UNIX socket',
5153
instanceOf: RequestError,
@@ -57,6 +59,25 @@ test('cannot redirect to unix protocol', withServer, async (t, server, got) => {
5759
});
5860
});
5961

62+
test('cannot redirect to UNIX protocol when UNIX sockets are not enabled', withServer, async (t, server, got) => {
63+
server.get('/protocol', unixProtocol);
64+
server.get('/hostname', unixHostname);
65+
66+
const gotUnixSocketsDisabled = got.extend({enableUnixSockets: false});
67+
68+
t.false(gotUnixSocketsDisabled.defaults.options.enableUnixSockets);
69+
70+
await t.throwsAsync(gotUnixSocketsDisabled('protocol'), {
71+
message: 'Cannot redirect to UNIX socket',
72+
instanceOf: RequestError,
73+
});
74+
75+
await t.throwsAsync(gotUnixSocketsDisabled('hostname'), {
76+
message: 'Cannot redirect to UNIX socket',
77+
instanceOf: RequestError,
78+
});
79+
});
80+
6081
test('follows redirect', withServer, async (t, server, got) => {
6182
server.get('/', reachedHandler);
6283
server.get('/finite', finiteHandler);

‎test/unix-socket.ts

+25
Original file line numberDiff line numberDiff line change
@@ -68,4 +68,29 @@ if (process.platform !== 'win32') {
6868
const url = format('http://unix:%s:%s', server.socketPath, '/');
6969
t.is((await got(url)).body, 'ok');
7070
});
71+
72+
test('`unix:` fails when UNIX sockets are not enabled', async t => {
73+
const gotUnixSocketsDisabled = got.extend({enableUnixSockets: false});
74+
75+
t.false(gotUnixSocketsDisabled.defaults.options.enableUnixSockets);
76+
await t.throwsAsync(
77+
gotUnixSocketsDisabled('unix:'),
78+
{
79+
message: 'Using UNIX domain sockets but option `enableUnixSockets` is not enabled',
80+
},
81+
);
82+
});
83+
84+
test('`http://unix:/` fails when UNIX sockets are not enabled', async t => {
85+
const gotUnixSocketsDisabled = got.extend({enableUnixSockets: false});
86+
87+
t.false(gotUnixSocketsDisabled.defaults.options.enableUnixSockets);
88+
89+
await t.throwsAsync(
90+
gotUnixSocketsDisabled('http://unix:'),
91+
{
92+
message: 'Using UNIX domain sockets but option `enableUnixSockets` is not enabled',
93+
},
94+
);
95+
});
7196
}

0 commit comments

Comments
 (0)