sockat 0.1.1__py3-none-any.whl

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.
sockat/__init__.py ADDED
@@ -0,0 +1,70 @@
1
+ """Bind / connect Unix domain sockets at paths longer than ``sun_path``.
2
+
3
+ Use :func:`bind` / :func:`connect` where you would create an ``AF_UNIX``
4
+ socket and call ``bind`` + ``listen`` / ``connect`` on it::
5
+
6
+ import sockat
7
+
8
+ listener = sockat.bind("/a/very/deep/directory/.../server.sock")
9
+ client = sockat.connect("/a/very/deep/directory/.../server.sock")
10
+
11
+ * The return value is a plain :class:`socket.socket`.
12
+ * A path the :mod:`socket` module accepts (``sun_path`` less 1 byte: 107 on
13
+ Linux, 103 on macOS and the BSDs) goes to it unchanged, so it behaves as the
14
+ standard library does.
15
+ * A longer path is reached by the routes of the sockat SPEC
16
+ (https://github.com/kawaz/sockat/blob/main/docs/SPEC.md), and the socket
17
+ file is created at the given path.
18
+
19
+ Errors are :class:`OSError` with the ``errno`` of the system call (so its
20
+ subclasses such as :class:`FileNotFoundError`), :class:`ValueError` for a
21
+ long path that does not end with a file name or contains a NUL byte, and an
22
+ :class:`OSError` without ``errno`` when the cwd changed during a bind /
23
+ connect through a path relative to it.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import socket
29
+ import sys
30
+
31
+ if sys.platform == "win32": # pragma: no cover
32
+ raise ImportError("sockat supports Unix systems only")
33
+
34
+ from ._route import BIND, CONNECT, CONNECT_NONBLOCKING, StrOrBytesPath, run
35
+
36
+ __all__ = ["bind", "connect", "connect_nonblocking"]
37
+
38
+
39
+ def bind(path: StrOrBytesPath) -> socket.socket:
40
+ """Create an ``AF_UNIX`` stream socket, bind it to ``path`` and listen
41
+ with the :mod:`socket` module's default backlog.
42
+
43
+ The same as ``socket.socket(AF_UNIX, SOCK_STREAM)`` followed by
44
+ ``bind(path)`` and ``listen()``, for any length of ``path``. The socket
45
+ file is not removed when the socket is closed (as with the standard
46
+ library); remove it with ``os.unlink(path)``.
47
+ """
48
+ return run(BIND, path)[0]
49
+
50
+
51
+ def connect(path: StrOrBytesPath) -> socket.socket:
52
+ """Create an ``AF_UNIX`` stream socket and connect it to ``path``
53
+ (blocking).
54
+
55
+ The same as ``socket.socket(AF_UNIX, SOCK_STREAM)`` followed by
56
+ ``connect(path)``, for any length of ``path``.
57
+ """
58
+ return run(CONNECT, path)[0]
59
+
60
+
61
+ def connect_nonblocking(path: StrOrBytesPath) -> socket.socket:
62
+ """Like :func:`connect`, but the socket is made nonblocking before the
63
+ connect and returned so, ready for an event loop (for example
64
+ ``asyncio.open_unix_connection(sock=...)``).
65
+
66
+ A Unix-domain connect completes or fails within the call, so nothing is
67
+ left to wait for. When the listener's backlog is full it fails at once
68
+ (Linux: :class:`BlockingIOError`, macOS: :class:`ConnectionRefusedError`).
69
+ """
70
+ return run(CONNECT_NONBLOCKING, path)[0]
sockat/_path.py ADDED
@@ -0,0 +1,95 @@
1
+ """Pure path arithmetic on the bytes of a socket path: splitting it into its
2
+ directory and file name, and spelling an absolute path relative to a working
3
+ directory. Nothing here touches the file system."""
4
+
5
+ from __future__ import annotations
6
+
7
+
8
+ def split(path: bytes) -> tuple[bytes, bytes]:
9
+ """Split a socket path into the directory that holds the socket and the
10
+ socket's file name, by the bytes after the last ``/``.
11
+
12
+ The split is done on the bytes rather than through a normalising path
13
+ library, which would drop a trailing ``/`` and ``.``: ``a/b/`` and
14
+ ``a/b/.`` would both come out as file name ``b``, while the kernel would
15
+ resolve them as the directory ``a/b`` itself. Such paths do not name a
16
+ socket file, so they are refused rather than silently retargeted.
17
+
18
+ ============== =========== =========
19
+ path directory file name
20
+ ============== =========== =========
21
+ ``/d/e/s.sock`` ``/d/e`` ``s.sock``
22
+ ``/s.sock`` ``/`` ``s.sock``
23
+ ``s.sock`` ``.`` ``s.sock``
24
+ ``d//s.sock`` ``d/`` ``s.sock``
25
+ ``d/``, ``d/.``, ``d/..``, ``..`` (ValueError)
26
+ ============== =========== =========
27
+
28
+ Raises:
29
+ ValueError: the last segment is empty, ``.`` or ``..``.
30
+ """
31
+ i = path.rfind(b"/")
32
+ if i == 0:
33
+ directory, name = b"/", path[1:]
34
+ elif i > 0:
35
+ directory, name = path[:i], path[i + 1 :]
36
+ else:
37
+ directory, name = b".", path
38
+ if name in (b"", b".", b".."):
39
+ raise ValueError("socket path must end with a file name (not '/', '.' or '..')")
40
+ return directory, name
41
+
42
+
43
+ def components(path: bytes) -> list[bytes]:
44
+ """The components of an absolute path after the root, as the kernel walks
45
+ them: empty segments (doubled slashes) and ``.`` are dropped, ``..`` is
46
+ kept as it is (it is not interpreted)."""
47
+ return [c for c in path.split(b"/") if c not in (b"", b".")]
48
+
49
+
50
+ def below(target: bytes, prefix: bytes) -> bytes | None:
51
+ """The part of ``target`` below the directory ``prefix``, when ``target``
52
+ starts with ``prefix`` component by component (``/a/b`` is a prefix of
53
+ ``/a/b/c`` but not of ``/a/bc``).
54
+
55
+ The result only descends from ``prefix`` along ``target``'s own
56
+ components, so it resolves through the same symlinks ``target`` does.
57
+ ``None`` when either is not absolute or ``prefix`` is not a proper prefix
58
+ (including ``target == prefix``, which leaves no file name).
59
+ """
60
+ if not target.startswith(b"/") or not prefix.startswith(b"/"):
61
+ return None
62
+ t = components(target)
63
+ p = components(prefix)
64
+ if len(t) <= len(p) or t[: len(p)] != p:
65
+ return None
66
+ return b"/".join(t[len(p) :])
67
+
68
+
69
+ def relative(target: bytes, cwd: bytes) -> bytes | None:
70
+ """Spell the absolute path ``target`` relative to the absolute directory
71
+ ``cwd``: climb with ``..`` out of the part of ``cwd`` that ``target`` does
72
+ not share, then descend along the rest of ``target``.
73
+
74
+ This is component arithmetic and is only meaningful when both inputs are
75
+ real paths (no symlinks, ``.`` or ``..``): ``cwd`` as ``getcwd(3)`` reports
76
+ it and ``target`` with its directory passed through ``realpath(3)``. Then
77
+ each ``..`` climbs out of a real directory, which is what the kernel does.
78
+ The caller still confirms that the result names the same directory before
79
+ using it.
80
+
81
+ ``None`` when either path is not absolute, or when ``target`` is ``cwd``
82
+ itself or one of its ancestors (there would be no file name left).
83
+ """
84
+ if not target.startswith(b"/") or not cwd.startswith(b"/"):
85
+ return None
86
+ t = components(target)
87
+ c = components(cwd)
88
+ common = 0
89
+ for a, b in zip(t, c, strict=False):
90
+ if a != b:
91
+ break
92
+ common += 1
93
+ if common >= len(t):
94
+ return None
95
+ return b"/".join([b".."] * (len(c) - common) + t[common:])
sockat/_route.py ADDED
@@ -0,0 +1,766 @@
1
+ """The order in which the ways of reaching a long socket path are tried
2
+ (docs/decisions/DR-0001, and the language-neutral SPEC of the hub
3
+ kawaz/sockat). :func:`run` is the only entry point used by the public API; the
4
+ per-route functions are module-level so the tests can force each route."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import contextlib
9
+ import errno
10
+ import os
11
+ import secrets
12
+ import socket
13
+ import sys
14
+ import threading
15
+ from collections.abc import Callable
16
+ from dataclasses import dataclass, field
17
+ from enum import Enum
18
+ from typing import TypeAlias
19
+
20
+ from . import _path
21
+ from ._sys import (
22
+ DIRECT_MAX,
23
+ HAS_THREAD_CWD,
24
+ IS_APPLE,
25
+ IS_FREEBSD,
26
+ IS_LINUX,
27
+ WIDE_PATH_MAX,
28
+ Op,
29
+ enter_dir_in_this_thread,
30
+ op,
31
+ op_at,
32
+ sockaddr,
33
+ )
34
+
35
+ StrOrBytesPath: TypeAlias = "str | bytes | os.PathLike[str] | os.PathLike[bytes]"
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Request:
40
+ """What to do at a path."""
41
+
42
+ op: Op
43
+ nonblocking: bool = False
44
+ """Make the socket nonblocking before the call, on every route, and leave
45
+ it so (``connect_nonblocking``). A full backlog then fails the connect at
46
+ once: Linux answers ``EAGAIN``, macOS ``ECONNREFUSED``. A Unix-domain
47
+ connect completes or fails within the call even on a nonblocking socket
48
+ (neither Linux nor XNU answers ``EINPROGRESS``)."""
49
+
50
+
51
+ BIND = Request(Op.BIND)
52
+ CONNECT = Request(Op.CONNECT)
53
+ CONNECT_NONBLOCKING = Request(Op.CONNECT, nonblocking=True)
54
+
55
+
56
+ class Route(Enum):
57
+ """Which way a bind / connect went. The public API does not show it."""
58
+
59
+ DIRECT = "direct"
60
+ """The path itself, through the ``socket`` module."""
61
+ PROC_FD = "proc-fd"
62
+ """``/proc/self/fd/<dirfd>/<name>``, through the ``socket`` module (Linux)."""
63
+ RELATIVE = "relative"
64
+ """The path spelled relative to the cwd, through the ``socket`` module."""
65
+ WIDE = "wide"
66
+ """The path itself in a widened ``sockaddr_un`` (Apple)."""
67
+ WIDE_RELATIVE = "wide-relative"
68
+ """The relative spelling in a widened ``sockaddr_un`` (Apple)."""
69
+ SYMLINK_TO_DIR = "symlink-to-dir"
70
+ """Through a short temporary symlink to the socket's directory (bind)."""
71
+ SYMLINK_TO_DIR_WIDE = "symlink-to-dir-wide"
72
+ """:attr:`SYMLINK_TO_DIR` in a widened ``sockaddr_un`` (Apple)."""
73
+ SYMLINK_TO_FILE = "symlink-to-file"
74
+ """Through a short temporary symlink to the socket file itself (connect)."""
75
+ SYMLINK_TO_FILE_WIDE = "symlink-to-file-wide"
76
+ """:attr:`SYMLINK_TO_FILE` in a widened ``sockaddr_un`` (Apple)."""
77
+ AT = "at"
78
+ """``bindat(2)`` / ``connectat(2)`` on the directory fd (FreeBSD)."""
79
+ THREAD_CWD = "thread-cwd"
80
+ """The file name, from a throwaway thread whose own cwd is the directory
81
+ (Linux, Apple)."""
82
+
83
+
84
+ def _enametoolong() -> OSError:
85
+ return OSError(errno.ENAMETOOLONG, os.strerror(errno.ENAMETOOLONG))
86
+
87
+
88
+ def _join(a: bytes, b: bytes) -> bytes:
89
+ return a + b if a.endswith(b"/") else a + b"/" + b
90
+
91
+
92
+ @dataclass(frozen=True)
93
+ class Config:
94
+ """What the route order reads from the environment, made explicit so the
95
+ tests can vary it without touching the process environment."""
96
+
97
+ tmp_bases: tuple[bytes, ...]
98
+ """Where the temporary symlink may go, in the order tried: ``TMPDIR``
99
+ when it is set to an absolute path, then ``/tmp``."""
100
+ wide: bool = IS_APPLE
101
+ """Whether to try the widened ``sockaddr_un`` at all (Apple). The tests
102
+ turn it off to stand in for a kernel that refuses the widened form."""
103
+ proc_self_fd: bytes = b"/proc/self/fd"
104
+ """Where the kernel lists the fds of the process (Linux). The tests point
105
+ it elsewhere to stand in for a system without /proc."""
106
+ thread_cwd: bool = HAS_THREAD_CWD
107
+ """Whether to try the thread-cwd route at all (Linux, Apple). The tests
108
+ turn it off to stand in for a system where it cannot be used."""
109
+
110
+ @classmethod
111
+ def from_env(cls) -> Config:
112
+ return cls.from_tmpdir(os.environb.get(b"TMPDIR"))
113
+
114
+ @classmethod
115
+ def from_tmpdir(cls, tmpdir: bytes | None) -> Config:
116
+ """The configuration for a ``TMPDIR`` of ``tmpdir``: ``TMPDIR``, then
117
+ ``/tmp``. An unset or empty ``TMPDIR`` leaves ``/tmp`` alone; a
118
+ relative one is left out (the link's place would depend on the cwd);
119
+ one that is ``/tmp`` itself is tried once."""
120
+ bases: list[bytes] = []
121
+ if tmpdir and tmpdir.startswith(b"/") and _path.components(tmpdir) != [b"tmp"]:
122
+ bases.append(tmpdir)
123
+ bases.append(b"/tmp")
124
+ return cls(tmp_bases=tuple(bases))
125
+
126
+
127
+ def run(req: Request, path: StrOrBytesPath) -> tuple[socket.socket, Route]:
128
+ """Bind (and listen) or connect a stream socket to ``path``, trying the
129
+ routes in order.
130
+
131
+ A path the ``socket`` module takes (at most :data:`DIRECT_MAX` bytes) goes
132
+ to it as is, before anything else is looked at (the environment included).
133
+
134
+ A NUL byte makes the path an argument error whatever its length (the
135
+ ``socket`` module would silently cut the path there), except a leading NUL
136
+ on Linux / Android: that is an address in the abstract namespace, not a
137
+ pathname, and goes to the ``socket`` module as is whatever its length.
138
+ """
139
+ spelled = os.fspath(path)
140
+ raw = os.fsencode(spelled)
141
+ if IS_LINUX and raw.startswith(b"\0"):
142
+ return plain_op(req, spelled), Route.DIRECT
143
+ check_no_nul(raw)
144
+ if len(raw) <= DIRECT_MAX:
145
+ return plain_op(req, spelled), Route.DIRECT
146
+ return run_long(req, raw, Config.from_env())
147
+
148
+
149
+ def check_no_nul(path: bytes) -> None:
150
+ """Raise :class:`ValueError` when ``path`` contains a NUL byte."""
151
+ if b"\0" in path:
152
+ raise ValueError("socket path must not contain a NUL byte")
153
+
154
+
155
+ def run_long(req: Request, path: bytes, cfg: Config) -> tuple[socket.socket, Route]:
156
+ """The routes for a path longer than :data:`DIRECT_MAX`, with what they
157
+ read from the environment given as ``cfg`` (the tests pass their own).
158
+
159
+ FreeBSD: ``bindat(2)`` / ``connectat(2)`` and nothing else. Linux:
160
+ ``/proc/self/fd/<dirfd>/<name>`` with the directory opened ``O_PATH``; when
161
+ that cannot be used, the POSIX order (:func:`posix_run`). Every other
162
+ system: the POSIX order.
163
+ """
164
+ check_no_nul(path)
165
+ directory, name = _path.split(path)
166
+ if IS_FREEBSD:
167
+ return at_op(req, directory, name), Route.AT
168
+ if IS_LINUX:
169
+ dirfd = open_dir(directory)
170
+ try:
171
+ via = proc_spelling(dirfd, name, cfg.proc_self_fd)
172
+ if via is not None:
173
+ return plain_op(req, via), Route.PROC_FD
174
+ return posix_run(req, path, directory, name, dirfd, cfg)
175
+ finally:
176
+ os.close(dirfd)
177
+ return posix_run(req, path, directory, name, None, cfg)
178
+
179
+
180
+ def new_socket(req: Request) -> socket.socket:
181
+ """A fresh ``AF_UNIX`` / ``SOCK_STREAM`` socket made by the ``socket``
182
+ module (so set up exactly as its own), nonblocking when ``req`` asks."""
183
+ sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
184
+ if req.nonblocking:
185
+ sock.setblocking(False)
186
+ return sock
187
+
188
+
189
+ def _finish(req: Request, sock: socket.socket, call: Callable[[socket.socket], None]) -> socket.socket:
190
+ """Run ``call`` on ``sock`` and listen after a bind; close ``sock`` on any
191
+ failure."""
192
+ try:
193
+ call(sock)
194
+ if req.op is Op.BIND:
195
+ sock.listen()
196
+ except BaseException:
197
+ sock.close()
198
+ raise
199
+ return sock
200
+
201
+
202
+ def plain_op(req: Request, spelling: str | bytes) -> socket.socket:
203
+ """Bind (and listen) or connect with ``spelling`` through the ``socket``
204
+ module, as a caller of the standard library would."""
205
+ sock = new_socket(req)
206
+ if req.op is Op.BIND:
207
+ return _finish(req, sock, lambda s: s.bind(spelling))
208
+ return _finish(req, sock, lambda s: s.connect(spelling))
209
+
210
+
211
+ def raw_op(req: Request, addr: bytes) -> socket.socket:
212
+ """Bind (and listen) or connect a fresh socket to the address bytes
213
+ ``addr`` through the C library (an address the ``socket`` module would
214
+ refuse)."""
215
+ sock = new_socket(req)
216
+ return _finish(req, sock, lambda s: op(req.op, s, addr))
217
+
218
+
219
+ def wide_op(req: Request, spelling: bytes) -> socket.socket:
220
+ """Bind (and listen) or connect a fresh socket to ``spelling`` in a
221
+ widened ``sockaddr_un`` (Apple)."""
222
+ return raw_op(req, sockaddr(spelling, wide=True))
223
+
224
+
225
+ def refuses_wide(e: OSError) -> bool:
226
+ """Whether an error from a widened-address call means the kernel does not
227
+ take the widened form (as opposed to a real outcome such as ``ENOENT``,
228
+ ``EADDRINUSE`` or ``ECONNREFUSED``). XNU reports an address it will not
229
+ take with ``EINVAL``, or ``ENAMETOOLONG`` for one longer than
230
+ ``SOCK_MAXADDRLEN``."""
231
+ return e.errno in (errno.EINVAL, errno.ENAMETOOLONG)
232
+
233
+
234
+ def open_dir(directory: bytes) -> int:
235
+ """Open ``directory`` to use as the base of a relative bind / connect
236
+ (close-on-exec, as :func:`os.open` makes every fd).
237
+
238
+ Linux: ``O_PATH | O_DIRECTORY``, which needs only search permission. The
239
+ fd serves the /proc route (``/proc/self/fd/<fd>`` names the directory).
240
+
241
+ Apple: ``O_SEARCH``, which needs only search permission; a kernel that does
242
+ not take ``O_SEARCH`` on a directory answers ``EISDIR`` or ``EINVAL``, and
243
+ then the directory is opened ``O_RDONLY`` (:func:`search_or_read_only`).
244
+
245
+ Other systems: ``O_RDONLY | O_DIRECTORY`` (needs read permission).
246
+ """
247
+ if sys.platform == "linux" or sys.platform == "android":
248
+ return os.open(directory, os.O_PATH | os.O_DIRECTORY)
249
+ if sys.platform == "darwin" or sys.platform == "ios":
250
+ return search_or_read_only(directory, lambda: os.open(directory, _APPLE_O_SEARCH))
251
+ return _open_read_only(directory)
252
+
253
+
254
+ _APPLE_O_SEARCH = 0x40000000 | os.O_DIRECTORY
255
+ """``O_SEARCH`` of Apple's ``<sys/fcntl.h>``: ``O_EXEC (0x40000000) |
256
+ O_DIRECTORY``.
257
+
258
+ Design rationale: written out rather than taken from ``os.O_SEARCH``, which
259
+ some Python builds for macOS do not have (the python-build-standalone 3.11 of
260
+ the CI lacks it; the module defines it only when the build saw the macro).
261
+ The value is the system's, not Python's, so it does not depend on the
262
+ build."""
263
+
264
+
265
+ def _open_read_only(directory: bytes) -> int:
266
+ return os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
267
+
268
+
269
+ def search_or_read_only(directory: bytes, search: Callable[[], int]) -> int:
270
+ """Open ``directory`` with ``search`` (``O_SEARCH``), unless it fails the
271
+ way a kernel that does not take ``O_SEARCH`` on a directory fails
272
+ (``EISDIR`` or ``EINVAL``); then open it ``O_RDONLY`` instead. Any other
273
+ error (``ENOENT``, ``EACCES``, ...) is the real outcome and is raised as
274
+ is. ``search`` is a parameter so the tests can stand in for such a
275
+ kernel."""
276
+ try:
277
+ return search()
278
+ except OSError as e:
279
+ if e.errno in (errno.EISDIR, errno.EINVAL):
280
+ return _open_read_only(directory)
281
+ raise
282
+
283
+
284
+ def proc_spelling(dirfd: int, name: bytes, proc_self_fd: bytes) -> bytes | None:
285
+ """``<proc_self_fd>/<dirfd>/<name>``, or ``None`` when the /proc route
286
+ cannot be used (Linux):
287
+
288
+ * ``<proc_self_fd>/<dirfd>`` cannot be looked up (no /proc). Without this
289
+ check a bind / connect through the spelling would fail with ``ENOENT``,
290
+ which reads as "the directory does not exist" although it does;
291
+ * the spelling does not fit ``sun_path`` (a file name of about 90 bytes or
292
+ more).
293
+ """
294
+ fd_dir = _join(proc_self_fd, str(dirfd).encode())
295
+ try:
296
+ os.stat(fd_dir)
297
+ except OSError:
298
+ return None
299
+ via = _join(fd_dir, name)
300
+ return via if len(via) <= DIRECT_MAX else None
301
+
302
+
303
+ def at_op(req: Request, directory: bytes, name: bytes) -> socket.socket:
304
+ """FreeBSD, for a path longer than :data:`DIRECT_MAX`: ``bindat(2)`` /
305
+ ``connectat(2)`` with the file name relative to the directory fd.
306
+
307
+ The directory is opened first, so a missing directory is ``ENOENT`` before
308
+ the length of the file name is judged."""
309
+ dirfd = open_dir(directory)
310
+ try:
311
+ addr = sockaddr(name)
312
+ sock = new_socket(req)
313
+ return _finish(req, sock, lambda s: op_at(req.op, s, dirfd, addr))
314
+ finally:
315
+ os.close(dirfd)
316
+
317
+
318
+ # ---------- the POSIX order ----------
319
+
320
+ SPELLING_MAX = WIDE_PATH_MAX if IS_APPLE else DIRECT_MAX
321
+ """The longest spelling a sockaddr carries on this system: the widened
322
+ form's 253 bytes on Apple, :data:`DIRECT_MAX` elsewhere."""
323
+
324
+
325
+ def posix_run(
326
+ req: Request,
327
+ path: bytes,
328
+ directory: bytes,
329
+ name: bytes,
330
+ opened: int | None,
331
+ cfg: Config,
332
+ ) -> tuple[socket.socket, Route]:
333
+ """Try, in order, for a path longer than :data:`DIRECT_MAX` whose
334
+ directory part is ``directory`` and file name ``name``:
335
+
336
+ 1. the path spelled relative to the cwd, when that is at most
337
+ :data:`DIRECT_MAX` bytes;
338
+ 2. (Apple) a widened ``sockaddr_un`` with the path itself, or failing that
339
+ with the relative spelling, when one of them is at most 253 bytes;
340
+ 3. a short symlink (:func:`symlink_route`: to the socket's directory for a
341
+ bind, to the socket file for a connect) under the first of
342
+ :attr:`Config.tmp_bases` where the path through it fits and the symlink
343
+ can be created;
344
+ 4. (Linux, Apple) the file name from a throwaway thread whose own cwd is
345
+ the directory (:func:`thread_cwd_op`);
346
+ 5. the place of the fork route, which this implementation does not have
347
+ (DR-0001): ``ENAMETOOLONG``.
348
+
349
+ Before 4 the directory is opened (``opened`` when the caller has it open
350
+ already, as Linux does), so a missing or unreadable directory is the real
351
+ error it is, before any length is judged.
352
+
353
+ A failure of a route ends the search with that error, except where it
354
+ shows that the route itself cannot be used (the kernel refusing the
355
+ widened form, the symlink not being creatable); then the next route (or
356
+ the next place for the symlink) is tried.
357
+ """
358
+ rel = Relative.new(path, directory)
359
+
360
+ if rel is not None and len(rel.path) <= DIRECT_MAX:
361
+ return rel.run(lambda p: plain_op(req, p)), Route.RELATIVE
362
+
363
+ wide = IS_APPLE and cfg.wide
364
+ if wide:
365
+ try:
366
+ if len(path) <= WIDE_PATH_MAX:
367
+ return wide_op(req, path), Route.WIDE
368
+ if rel is not None and len(rel.path) <= WIDE_PATH_MAX:
369
+ return rel.run(lambda p: wide_op(req, p)), Route.WIDE_RELATIVE
370
+ except OSError as e:
371
+ if not refuses_wide(e):
372
+ raise
373
+ wide = False
374
+
375
+ for base in cfg.tmp_bases:
376
+ limit = WIDE_PATH_MAX if wide else DIRECT_MAX
377
+ outcome = symlink_route(req, base, path, directory, name, limit)
378
+ if isinstance(outcome, tuple):
379
+ return outcome
380
+ if outcome is Skip.WIDE_REFUSED:
381
+ wide = False
382
+
383
+ dirfd = opened if opened is not None else open_dir(directory)
384
+ try:
385
+ if cfg.thread_cwd:
386
+ done = thread_cwd_op(req, dirfd, name, wide)
387
+ if isinstance(done, socket.socket):
388
+ return done, Route.THREAD_CWD
389
+ finally:
390
+ if opened is None:
391
+ os.close(dirfd)
392
+ # The place of the fork route (bind; the SPEC's connect_any family), which
393
+ # this implementation does not have (DR-0001): what a plain bind / connect
394
+ # of a path longer than sun_path answers.
395
+ raise _enametoolong()
396
+
397
+
398
+ def thread_cwd_op(req: Request, dirfd: int, name: bytes, wide: bool) -> socket.socket | Skip:
399
+ """Bind (and listen) or connect a fresh socket to ``name`` from a
400
+ throwaway :class:`threading.Thread` whose own cwd is the directory
401
+ ``dirfd`` (:func:`._sys.enter_dir_in_this_thread`: ``unshare(CLONE_FS)``
402
+ then ``fchdir(2)`` on Linux, ``pthread_fchdir_np`` on Apple). The process
403
+ cwd, and so every other thread's, never changes; the thread ends with the
404
+ call.
405
+
406
+ :attr:`Skip.UNUSABLE` when the route cannot be used: the file name does
407
+ not fit a sockaddr (the widened one on Apple when ``wide``), the thread
408
+ cannot be started, or the system refuses a cwd of the thread's own
409
+ (a seccomp filter on, as under docker's default, or ``unshare`` refused; no
410
+ ``pthread_fchdir_np``, or it failed), or the kernel refuses the widened
411
+ sockaddr a file name over :data:`DIRECT_MAX` bytes needs (Apple:
412
+ :func:`refuses_wide`). Any other failure is the outcome.
413
+ """
414
+ limit = WIDE_PATH_MAX if wide else DIRECT_MAX
415
+ if len(name) > limit:
416
+ return Skip.UNUSABLE
417
+ addr = sockaddr(name, wide=True) if len(name) > DIRECT_MAX else None
418
+ sock = new_socket(req)
419
+ outcome: list[BaseException | Skip | None] = []
420
+ # Who closes `sock` when the caller stops waiting (an exception such as
421
+ # KeyboardInterrupt out of join): the thread may still be using it, so it
422
+ # is handed over to the thread, which closes it when it ends.
423
+ handover = threading.Lock()
424
+ ended = False
425
+ abandoned = False
426
+
427
+ def in_thread() -> None:
428
+ nonlocal ended
429
+ try:
430
+ run_in_thread()
431
+ finally:
432
+ with handover:
433
+ ended = True
434
+ if abandoned:
435
+ sock.close()
436
+
437
+ def run_in_thread() -> None:
438
+ try:
439
+ if not enter_dir_in_this_thread(dirfd):
440
+ outcome.append(Skip.UNUSABLE)
441
+ return
442
+ if addr is not None:
443
+ op(req.op, sock, addr)
444
+ elif req.op is Op.BIND:
445
+ sock.bind(name)
446
+ else:
447
+ sock.connect(name)
448
+ outcome.append(None)
449
+ except BaseException as e:
450
+ outcome.append(e)
451
+
452
+ thread = threading.Thread(target=in_thread, name="sockat-thread-cwd")
453
+ try:
454
+ thread.start()
455
+ except RuntimeError:
456
+ sock.close()
457
+ return Skip.UNUSABLE
458
+ try:
459
+ thread.join()
460
+ except BaseException:
461
+ with handover:
462
+ if ended:
463
+ sock.close()
464
+ else:
465
+ abandoned = True
466
+ raise
467
+ result = outcome[0] if outcome else RuntimeError("the thread-cwd thread ended without an outcome")
468
+ if result is Skip.UNUSABLE or (isinstance(result, OSError) and addr is not None and refuses_wide(result)):
469
+ sock.close()
470
+ return Skip.UNUSABLE
471
+ if isinstance(result, BaseException):
472
+ sock.close()
473
+ raise result
474
+ return _finish(req, sock, lambda s: None)
475
+
476
+
477
+ def _dir_id(directory: bytes) -> tuple[int, int] | None:
478
+ try:
479
+ st = os.stat(directory)
480
+ except OSError:
481
+ return None
482
+ return st.st_dev, st.st_ino
483
+
484
+
485
+ def _cwd_spellings(cwd: bytes, cwd_id: tuple[int, int]) -> list[bytes]:
486
+ """The spellings of the cwd that the path may start with: what
487
+ ``getcwd(3)`` reports (a real path), and ``$PWD`` (the path the shell used
488
+ to get there, possibly through symlinks) but only when it names the cwd.
489
+
490
+ ``$PWD`` is just an environment variable: it is stale after a ``chdir(2)``
491
+ that did not update it, and anyone can set it. It is used only when
492
+ ``stat($PWD)`` and ``stat(".")`` agree on ``(st_dev, st_ino)``.
493
+ """
494
+ spellings = [cwd]
495
+ pwd = os.environb.get(b"PWD")
496
+ if pwd and pwd.startswith(b"/") and pwd != cwd and _dir_id(pwd) == cwd_id:
497
+ spellings.append(pwd)
498
+ return spellings
499
+
500
+
501
+ class CwdChanged(OSError):
502
+ """Raised by :meth:`Relative.run` when the cwd changed during the call.
503
+ Not exported: callers see an :class:`OSError` without an errno."""
504
+
505
+
506
+ @dataclass(frozen=True)
507
+ class Relative:
508
+ """A relative spelling of an absolute socket path, checked to name the
509
+ same directory as the absolute one."""
510
+
511
+ path: bytes
512
+ cwd: tuple[int, int] = field(repr=False)
513
+ """``(st_dev, st_ino)`` of the cwd when the spelling was made."""
514
+
515
+ @classmethod
516
+ def new(cls, path: bytes, directory: bytes) -> Relative | None:
517
+ """Spell ``path`` (whose directory part is ``directory``) relative to
518
+ the cwd.
519
+
520
+ Two ways, the first one first:
521
+
522
+ 1. **Below the cwd.** When ``path`` starts, component by component,
523
+ with a spelling of the cwd (``getcwd(3)``, or a ``$PWD`` that names
524
+ the cwd), cut that prefix off. The rest only descends from the cwd
525
+ along ``path`` itself, so it resolves the same way ``path`` does.
526
+ 2. **Through real paths.** Only when 1 gives nothing of at most
527
+ :data:`DIRECT_MAX` bytes: resolve ``directory`` with ``realpath(3)``
528
+ and climb out of the cwd as ``getcwd(3)`` reports it (both real, so
529
+ every ``..`` climbs out of a real directory, as the kernel does).
530
+
531
+ The shorter result is kept. ``None`` when ``path`` is not absolute,
532
+ the cwd cannot be read, neither way gives a spelling a sockaddr of
533
+ this system carries (:data:`SPELLING_MAX`), or the relative directory
534
+ turns out not to be the absolute one.
535
+ """
536
+ if not path.startswith(b"/"):
537
+ return None
538
+ _, name = _path.split(path)
539
+ cwd_before = _dir_id(b".")
540
+ if cwd_before is None:
541
+ return None
542
+ try:
543
+ cwd = os.getcwdb()
544
+ except OSError:
545
+ return None
546
+
547
+ best: bytes | None = None
548
+ for prefix in _cwd_spellings(cwd, cwd_before):
549
+ rel = _path.below(path, prefix)
550
+ if rel is not None and (best is None or len(rel) < len(best)):
551
+ best = rel
552
+ if best is None or len(best) > DIRECT_MAX:
553
+ try:
554
+ real_dir = os.fsencode(os.path.realpath(directory, strict=True))
555
+ except OSError:
556
+ real_dir = None
557
+ if real_dir is not None:
558
+ rel = _path.relative(_join(real_dir, name), cwd)
559
+ if rel is not None and (best is None or len(rel) < len(best)):
560
+ best = rel
561
+ if best is None or len(best) > SPELLING_MAX:
562
+ return None
563
+ rel_dir, _ = _path.split(best)
564
+ rel_id = _dir_id(rel_dir)
565
+ if rel_id is None or rel_id != _dir_id(directory):
566
+ return None
567
+ if _dir_id(b".") != cwd_before:
568
+ return None
569
+ return cls(path=best, cwd=cwd_before)
570
+
571
+ def run(self, f: Callable[[bytes], socket.socket]) -> socket.socket:
572
+ """Run ``f`` with the relative spelling, then confirm the cwd is still
573
+ the one the spelling was made against.
574
+
575
+ If another thread changed the cwd in between, the call went to some
576
+ other directory: the result is discarded (a socket is closed) and
577
+ :class:`CwdChanged` is raised. A socket file that such a bind created
578
+ is left where it is, because the directory it went to is unknown. The
579
+ check cannot see a change that is undone before it runs; the guarantee
580
+ is for processes that do not change the cwd while binding /
581
+ connecting.
582
+ """
583
+ result: socket.socket | None = None
584
+ failure: OSError | None = None
585
+ try:
586
+ result = f(self.path)
587
+ except OSError as e:
588
+ failure = e
589
+ if _dir_id(b".") != self.cwd:
590
+ if result is not None:
591
+ result.close()
592
+ raise CwdChanged(
593
+ "the current directory changed while binding / connecting through a path "
594
+ "relative to it; the result was discarded"
595
+ ) from failure
596
+ if failure is not None:
597
+ raise failure
598
+ assert result is not None
599
+ return result
600
+
601
+
602
+ # ---------- the symlink route ----------
603
+
604
+
605
+ class Skip(Enum):
606
+ """Why :func:`symlink_route` did not run."""
607
+
608
+ UNUSABLE = "unusable"
609
+ """The route could not be used (too long, no usable base, symlink not
610
+ creatable)."""
611
+ WIDE_REFUSED = "wide-refused"
612
+ """The path through the symlink needed the widened form and the kernel
613
+ refused it (Apple)."""
614
+
615
+
616
+ LINK_PREFIX = b"sockat."
617
+ """What the symlink name starts with, so a link left behind by a process that
618
+ died is recognisable as sockat's."""
619
+
620
+ LINK_RANDOM_LEN = 10
621
+ """Length of the random part of the symlink name (``sockat.XXXXXXXXXX``)."""
622
+
623
+ _ALPHABET = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
624
+
625
+
626
+ def random_name() -> bytes:
627
+ """``sockat.`` followed by :data:`LINK_RANDOM_LEN` random letters and
628
+ digits from the system's secure generator (:mod:`secrets`; when it fails,
629
+ the symlink route cannot be used)."""
630
+ return LINK_PREFIX + bytes(secrets.choice(_ALPHABET) for _ in range(LINK_RANDOM_LEN))
631
+
632
+
633
+ def symlink_route(
634
+ req: Request,
635
+ base: bytes,
636
+ path: bytes,
637
+ directory: bytes,
638
+ name: bytes,
639
+ limit: int,
640
+ ) -> tuple[socket.socket, Route] | Skip:
641
+ """Bind / connect ``path`` (directory part ``directory``, file name
642
+ ``name``) through a symlink ``<base>/sockat.XXXXXXXXXX``:
643
+
644
+ ======= ================== ============================== =========================
645
+ request the link points to spelling handed to the kernel route
646
+ ======= ================== ============================== =========================
647
+ bind ``directory`` ``<link>/<name>`` :attr:`Route.SYMLINK_TO_DIR`
648
+ connect ``path`` ``<link>`` :attr:`Route.SYMLINK_TO_FILE`
649
+ ======= ================== ============================== =========================
650
+
651
+ A connect follows a symlink in the last component, so the link to the
652
+ file reaches the socket by a spelling whose length depends on neither the
653
+ directory nor the file name. A bind does not: Linux refuses it with
654
+ ``EADDRINUSE``. Both links hold the caller's own spelling (made absolute
655
+ against the cwd), so the kernel resolves them as it resolves ``path``.
656
+
657
+ Used when the spelling is at most ``limit`` bytes (:data:`DIRECT_MAX` for
658
+ the plain sockaddr, or on Apple the widened form's 253) and ``base`` is a
659
+ place where nobody else can replace the symlink (:func:`safe_base`). Both
660
+ are checked before anything is created. Nothing is left under ``base``:
661
+ the symlink is removed when this returns, whatever the outcome.
662
+ """
663
+ to_file = req.op is Op.CONNECT
664
+ placeholder = _join(base, LINK_PREFIX + b"X" * LINK_RANDOM_LEN)
665
+ spelling_len = len(placeholder) if to_file else len(_join(placeholder, name))
666
+ if spelling_len > limit or not safe_base(base):
667
+ return Skip.UNUSABLE
668
+ target = path if to_file else directory
669
+ if not target.startswith(b"/"):
670
+ try:
671
+ target = _join(os.getcwdb(), target)
672
+ except OSError:
673
+ return Skip.UNUSABLE
674
+ try:
675
+ link = TempLink.create(base, target)
676
+ except (OSError, NotImplementedError):
677
+ return Skip.UNUSABLE
678
+ with link:
679
+ if to_file:
680
+ via, plain_route, wide_route = link.path, Route.SYMLINK_TO_FILE, Route.SYMLINK_TO_FILE_WIDE
681
+ else:
682
+ via, plain_route, wide_route = _join(link.path, name), Route.SYMLINK_TO_DIR, Route.SYMLINK_TO_DIR_WIDE
683
+ if IS_APPLE and len(via) > DIRECT_MAX:
684
+ try:
685
+ return wide_op(req, via), wide_route
686
+ except OSError as e:
687
+ if refuses_wide(e):
688
+ return Skip.WIDE_REFUSED
689
+ raise
690
+ return plain_op(req, via), plain_route
691
+
692
+
693
+ def safe_base(base: bytes) -> bool:
694
+ """Whether ``base``, followed through symlinks (macOS's ``/tmp`` is one to
695
+ ``/private/tmp``), is a directory where no other user (root aside) can
696
+ remove or rename an entry, so the symlink cannot be replaced between its
697
+ creation and the bind / connect through it (:func:`only_we_can_replace`).
698
+ ``False`` when it cannot be looked up."""
699
+ try:
700
+ st = os.stat(base)
701
+ except OSError:
702
+ return False
703
+ return only_we_can_replace(st.st_mode, st.st_uid, os.geteuid())
704
+
705
+
706
+ def only_we_can_replace(mode: int, owner: int, us: int) -> bool:
707
+ """Whether, in a directory of ``mode`` owned by ``owner``, only the user
708
+ ``us`` and root can remove or rename the entries ``us`` creates:
709
+
710
+ * **sticky** (``S_ISVTX``, as ``/tmp`` is) **and owned by root or us**: an
711
+ entry can then be removed or renamed only by its owner, the directory's
712
+ owner and root;
713
+ * **owned by us with no write permission for group and others**
714
+ (``mode & 0o022 == 0``, as a private ``TMPDIR`` is): nobody else can
715
+ create, remove or rename entries there at all.
716
+ """
717
+ sticky = 0o1000
718
+ group_or_other_write = 0o022
719
+ ours = owner in (us, 0)
720
+ return (bool(mode & sticky) and ours) or (owner == us and mode & group_or_other_write == 0)
721
+
722
+
723
+ class TempLink:
724
+ """A symlink under a base directory with a random name, removed when the
725
+ ``with`` block ends."""
726
+
727
+ ATTEMPTS = 16
728
+ """How many names to try before giving up. Each try is a fresh random name
729
+ from 62^10 possibilities, so exhausting this means something other than
730
+ bad luck (for example a base that refuses every name)."""
731
+
732
+ def __init__(self, path: bytes) -> None:
733
+ self.path = path
734
+
735
+ @classmethod
736
+ def create(
737
+ cls,
738
+ base: bytes,
739
+ target: bytes,
740
+ next_name: Callable[[], bytes] = random_name,
741
+ ) -> TempLink:
742
+ """Create a symlink under ``base`` pointing to ``target``, named by
743
+ ``next_name`` (called once per try; its error ends the attempt).
744
+
745
+ ``symlink(2)`` fails with ``EEXIST`` instead of replacing an existing
746
+ entry, which is the ``O_EXCL`` of symlinks: the link that is created is
747
+ always one nobody else had, and a name already taken (by anyone) is
748
+ skipped for the next one. Any other error ends the attempt.
749
+ """
750
+ for _ in range(cls.ATTEMPTS):
751
+ link = _join(base, next_name())
752
+ try:
753
+ os.symlink(target, link)
754
+ except FileExistsError:
755
+ continue
756
+ return cls(link)
757
+ raise FileExistsError(errno.EEXIST, "could not find a free name for a temporary symlink")
758
+
759
+ def __enter__(self) -> TempLink:
760
+ return self
761
+
762
+ def __exit__(self, *exc: object) -> None:
763
+ # Best effort: the socket is already bound / connected, and failing it
764
+ # now would not bring the symlink back either.
765
+ with contextlib.suppress(OSError):
766
+ os.unlink(self.path)
sockat/_sys.py ADDED
@@ -0,0 +1,247 @@
1
+ """The boundary to the C library. Every call that the ``socket`` module cannot
2
+ make (an address it would refuse, a system call it does not wrap) goes
3
+ through :mod:`ctypes` here, and only here.
4
+
5
+ Contents:
6
+
7
+ * :data:`SUN_PATH_CAP` / :data:`DIRECT_MAX` — the length of ``sun_path`` on
8
+ this system and the longest path the ``socket`` module takes.
9
+ * :func:`sockaddr` — a ``sockaddr_un`` built by hand, in the standard form or
10
+ (Apple) the widened form whose path runs past ``sun_path`` up to
11
+ :data:`WIDE_PATH_MAX` bytes.
12
+ * :func:`op` — ``bind(2)`` / ``connect(2)`` of a ``socket.socket`` with such an
13
+ address.
14
+ * :func:`op_at` — ``bindat(2)`` / ``connectat(2)`` (FreeBSD).
15
+ * :func:`enter_dir_in_this_thread` — a cwd of the calling thread's own
16
+ (Linux: ``unshare(CLONE_FS)``, Apple: ``pthread_fchdir_np``).
17
+
18
+ :mod:`ctypes` is imported on first use, so a system that never needs these
19
+ calls (Linux, whose long paths go through /proc) never loads it.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import errno
25
+ import os
26
+ import select
27
+ import socket
28
+ import struct
29
+ import sys
30
+ from enum import Enum
31
+ from typing import TYPE_CHECKING
32
+
33
+ if TYPE_CHECKING:
34
+ import ctypes
35
+
36
+
37
+ class Op(Enum):
38
+ """What to do with a socket and an address."""
39
+
40
+ BIND = "bind"
41
+ """``bind(2)``; the caller listens afterwards."""
42
+ CONNECT = "connect"
43
+ """``connect(2)``."""
44
+
45
+
46
+ def _platform_family() -> str:
47
+ """The family of ``sys.platform`` that decides the ``sockaddr_un`` layout."""
48
+ p = sys.platform
49
+ for prefix in ("darwin", "ios", "freebsd", "netbsd", "openbsd", "dragonfly"):
50
+ if p.startswith(prefix):
51
+ return "bsd"
52
+ return p
53
+
54
+
55
+ IS_APPLE = sys.platform in ("darwin", "ios")
56
+ """Apple's kernel (XNU), which takes the widened ``sockaddr_un``."""
57
+ IS_LINUX = sys.platform.startswith("linux") or sys.platform == "android"
58
+ """Linux and Android, which have ``/proc/self/fd``."""
59
+ IS_FREEBSD = sys.platform.startswith("freebsd")
60
+ """FreeBSD, which has ``bindat(2)`` / ``connectat(2)``."""
61
+ _BSD_LAYOUT = _platform_family() == "bsd"
62
+ """``sockaddr_un`` starts with a 1-byte ``sun_len`` then a 1-byte family (the
63
+ BSDs and Apple); elsewhere with a 2-byte family."""
64
+
65
+ SUN_PATH_OFFSET = 2
66
+ """Offset of ``sun_path`` in ``struct sockaddr_un`` (2 on every supported
67
+ system)."""
68
+
69
+ SUN_PATH_CAP = 104 if _BSD_LAYOUT else 108
70
+ """Length of the ``sun_path`` array of ``struct sockaddr_un``: 104 on the BSDs
71
+ and Apple, 108 on Linux, Android and illumos. The ``socket`` module refuses a
72
+ path of this many bytes or more (``path.len >= sizeof sun_path`` in CPython's
73
+ ``socketmodule.c``), so a path fits the standard form when it is shorter."""
74
+
75
+ DIRECT_MAX = SUN_PATH_CAP - 1
76
+ """The longest path the ``socket`` module takes, ``sun_path`` less the NUL:
77
+ 107 on Linux, Android and illumos, 103 on Apple and the BSDs."""
78
+
79
+ WIDE_PATH_MAX = 253
80
+ """Longest path the widened ``sockaddr_un`` carries on Apple systems.
81
+
82
+ XNU accepts a socket address of up to ``SOCK_MAXADDRLEN`` (255) bytes in
83
+ ``bind(2)`` / ``connect(2)`` and takes ``sun_len - offsetof(sun_path)`` bytes
84
+ as the path, requiring that to be less than ``SOCK_MAXADDRLEN``. With the
85
+ length byte and the family byte in front, 253 bytes of path fit, without a
86
+ NUL. libuv uses the same layout (#5047)."""
87
+
88
+
89
+ def _check_bytes(path: bytes) -> None:
90
+ if not path:
91
+ raise ValueError("socket path is empty")
92
+ if b"\0" in path:
93
+ raise ValueError("socket path must not contain a NUL byte")
94
+
95
+
96
+ def _enametoolong() -> OSError:
97
+ return OSError(errno.ENAMETOOLONG, os.strerror(errno.ENAMETOOLONG))
98
+
99
+
100
+ def sockaddr(path: bytes, *, wide: bool = False) -> bytes:
101
+ """The bytes of a ``sockaddr_un`` holding ``path``.
102
+
103
+ Standard form: ``path`` must be shorter than :data:`SUN_PATH_CAP`, and the
104
+ address carries a terminating NUL (the bytes the ``socket`` module builds).
105
+
106
+ Widened form (``wide``, Apple only): up to :data:`WIDE_PATH_MAX` bytes of
107
+ path, no terminating NUL, ``sun_len`` and the address length both
108
+ ``2 + len(path)``.
109
+
110
+ Raises:
111
+ ValueError: ``path`` is empty or contains a NUL byte.
112
+ OSError: ``ENAMETOOLONG`` when it does not fit.
113
+ """
114
+ _check_bytes(path)
115
+ if wide:
116
+ if not IS_APPLE:
117
+ raise AssertionError("the widened sockaddr_un exists on Apple systems only")
118
+ if len(path) > WIDE_PATH_MAX:
119
+ raise _enametoolong()
120
+ length = SUN_PATH_OFFSET + len(path)
121
+ body = path
122
+ else:
123
+ if len(path) >= SUN_PATH_CAP:
124
+ raise _enametoolong()
125
+ length = SUN_PATH_OFFSET + len(path) + 1
126
+ body = path + b"\0"
127
+ header = struct.pack("=BB", length, socket.AF_UNIX) if _BSD_LAYOUT else struct.pack("=H", socket.AF_UNIX)
128
+ return header + body
129
+
130
+
131
+ _libc: ctypes.CDLL | None = None
132
+
133
+
134
+ def _c() -> ctypes.CDLL:
135
+ """The C library, loaded on first use with ``errno`` captured per call."""
136
+ global _libc
137
+ if _libc is None:
138
+ import ctypes as c
139
+
140
+ _libc = c.CDLL(None, use_errno=True)
141
+ return _libc
142
+
143
+
144
+ def _raise_errno(err: int) -> None:
145
+ raise OSError(err, os.strerror(err))
146
+
147
+
148
+ def _wait_connected(sock: socket.socket) -> None:
149
+ """Finish a ``connect(2)`` that was interrupted by a signal, as the
150
+ ``socket`` module does (bpo-23618): the connection goes on in the kernel,
151
+ so wait until the socket is writable (within the socket's timeout) and read
152
+ the outcome from ``SO_ERROR``."""
153
+ timeout = sock.gettimeout()
154
+ poller = select.poll()
155
+ poller.register(sock.fileno(), select.POLLOUT)
156
+ ready = poller.poll(None if timeout is None else timeout * 1000)
157
+ if not ready:
158
+ raise TimeoutError("timed out")
159
+ err = sock.getsockopt(socket.SOL_SOCKET, socket.SO_ERROR)
160
+ if err:
161
+ _raise_errno(err)
162
+
163
+
164
+ def op(which: Op, sock: socket.socket, addr: bytes) -> None:
165
+ """``bind(2)`` or ``connect(2)`` on ``sock`` with the address bytes
166
+ ``addr`` (from :func:`sockaddr`).
167
+
168
+ A connect interrupted by a signal (``EINTR``) is finished as the
169
+ ``socket`` module finishes its own: a blocking socket waits for the
170
+ outcome, a nonblocking one raises ``InterruptedError``.
171
+ """
172
+ import ctypes as c
173
+
174
+ fn = _c().bind if which is Op.BIND else _c().connect
175
+ buf = c.create_string_buffer(addr, len(addr))
176
+ rc: int = fn(c.c_int(sock.fileno()), buf, c.c_uint32(len(addr)))
177
+ if rc == 0:
178
+ return
179
+ err = c.get_errno()
180
+ if which is Op.CONNECT and err == errno.EINTR and sock.gettimeout() != 0.0:
181
+ _wait_connected(sock)
182
+ return
183
+ _raise_errno(err)
184
+
185
+
186
+ def op_at(which: Op, sock: socket.socket, dirfd: int, addr: bytes) -> None:
187
+ """``bindat(2)`` / ``connectat(2)`` with ``addr`` resolved relative to the
188
+ directory ``dirfd`` (FreeBSD 10+), with the same ``EINTR`` handling as
189
+ :func:`op`."""
190
+ import ctypes as c
191
+
192
+ fn = _c().bindat if which is Op.BIND else _c().connectat
193
+ buf = c.create_string_buffer(addr, len(addr))
194
+ rc: int = fn(c.c_int(dirfd), c.c_int(sock.fileno()), buf, c.c_uint32(len(addr)))
195
+ if rc == 0:
196
+ return
197
+ err = c.get_errno()
198
+ if which is Op.CONNECT and err == errno.EINTR and sock.gettimeout() != 0.0:
199
+ _wait_connected(sock)
200
+ return
201
+ _raise_errno(err)
202
+
203
+
204
+ HAS_THREAD_CWD = IS_LINUX or IS_APPLE
205
+ """Whether this system has a way to give one thread a cwd of its own."""
206
+
207
+ _CLONE_FS = 0x200
208
+ """``CLONE_FS`` of ``<sched.h>`` (Linux)."""
209
+
210
+ _PR_GET_SECCOMP = 21
211
+ """``PR_GET_SECCOMP`` of ``<linux/prctl.h>``."""
212
+
213
+
214
+ def enter_dir_in_this_thread(dirfd: int) -> bool:
215
+ """Make the directory ``dirfd`` the cwd of the calling thread only, and
216
+ ``True``; ``False`` when the system will not give the thread a cwd of its
217
+ own. The process cwd, which every other thread keeps using, is not
218
+ changed. Call it only from a thread made for the purpose and thrown away
219
+ afterwards: the thread keeps that cwd until it ends.
220
+
221
+ * Linux: ``unshare(CLONE_FS)`` (the thread stops sharing the cwd with the
222
+ rest of the process), then ``fchdir(dirfd)`` (its failure is raised).
223
+ ``False`` without calling ``unshare`` when a seccomp filter is on
224
+ (``prctl(PR_GET_SECCOMP)`` is not 0): a filter may answer ``unshare``
225
+ by killing the process (``SIGSYS``, as systemd's ``SystemCallFilter=``
226
+ does) rather than with an error. ``False`` also when ``unshare`` is
227
+ refused.
228
+ * Apple: ``pthread_fchdir_np(dirfd)``, a private libSystem function looked
229
+ up at run time (``False`` when it is missing or fails).
230
+ """
231
+ import ctypes as c
232
+
233
+ if IS_LINUX:
234
+ if _c().prctl(c.c_int(_PR_GET_SECCOMP), c.c_ulong(0), c.c_ulong(0), c.c_ulong(0), c.c_ulong(0)) != 0:
235
+ return False
236
+ if _c().unshare(c.c_int(_CLONE_FS)) != 0:
237
+ return False
238
+ os.fchdir(dirfd)
239
+ return True
240
+ if IS_APPLE:
241
+ try:
242
+ fchdir_np = _c().pthread_fchdir_np
243
+ except AttributeError:
244
+ return False
245
+ rc: int = fchdir_np(c.c_int(dirfd))
246
+ return rc == 0
247
+ return False
sockat/py.typed ADDED
File without changes
@@ -0,0 +1,122 @@
1
+ Metadata-Version: 2.4
2
+ Name: sockat
3
+ Version: 0.1.1
4
+ Summary: Bind / connect Unix domain sockets at paths longer than sun_path
5
+ Keywords: unix,socket,sun_path,AF_UNIX,ENAMETOOLONG
6
+ Author: Yoshiaki Kawazu
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Operating System :: POSIX
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Operating System :: POSIX :: BSD
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Topic :: System :: Networking
18
+ Classifier: Typing :: Typed
19
+ Requires-Python: >=3.11
20
+ Project-URL: Homepage, https://github.com/kawaz/sockat-py
21
+ Project-URL: Repository, https://github.com/kawaz/sockat-py
22
+ Project-URL: Specification, https://github.com/kawaz/sockat/blob/main/docs/SPEC.md
23
+ Description-Content-Type: text/markdown
24
+
25
+ # sockat
26
+
27
+ > English | [日本語](./README-ja.md)
28
+
29
+ A Python library that binds and connects Unix domain sockets even when the path is longer than `sun_path` allows (104 bytes on macOS and the BSDs, 108 on Linux, NUL included).
30
+
31
+ The language-independent behaviour is defined by the [sockat specification](https://github.com/kawaz/sockat/blob/main/docs/SPEC.md); sockat-py is its Python implementation.
32
+
33
+ ```python
34
+ import sockat
35
+
36
+ listener = sockat.bind("/a/very/deep/directory/.../server.sock")
37
+ client = sockat.connect("/a/very/deep/directory/.../server.sock")
38
+ ```
39
+
40
+ ## Usage
41
+
42
+ ```sh
43
+ pip install sockat
44
+ ```
45
+
46
+ Use `sockat.bind` / `sockat.connect` instead of creating a `socket.socket(AF_UNIX, SOCK_STREAM)` and calling `bind` + `listen` / `connect`. In an event loop such as asyncio, use `sockat.connect_nonblocking`, which does not wait and returns a nonblocking socket.
47
+
48
+ | Function | Standard library code it replaces | Returns |
49
+ |---|---|---|
50
+ | `sockat.bind(path)` | `socket()` → `bind(path)` → `listen()` | a listening `socket.socket` |
51
+ | `sockat.connect(path)` | `socket()` → `connect(path)` | a `socket.socket` |
52
+ | `sockat.connect_nonblocking(path)` | `socket()` → `setblocking(False)` → `connect(path)` | a nonblocking `socket.socket` |
53
+
54
+ - The results are the standard library's own `socket.socket`
55
+ - A path that the standard library accepts is handed to it unchanged, so it behaves exactly as with the standard library
56
+ - Even for a long path, the socket file is created at the path given
57
+ - `path` is a `str` / `bytes` / `os.PathLike`
58
+ - Python 3.11 or later. No dependencies (pure Python)
59
+
60
+ ## Why
61
+
62
+ The standard library's `socket.bind` / `socket.connect` refuse a path that does not fit `sun_path` with `OSError('AF_UNIX path too long')`. The file system has no such limit, but deep temporary directories hit it quickly (macOS's `$TMPDIR` alone is about 50 bytes, and test harnesses and sandboxes nest further). The limit applies to the argument passed to `bind(2)` / `connect(2)`, so sockat hands the kernel a short spelling that names the same place.
63
+
64
+ ## How a long path is reached
65
+
66
+ A path that the standard library accepts (up to `sun_path` − 1 bytes) is handed to it unchanged.
67
+
68
+ | OS | Handed to the standard library |
69
+ |---|---|
70
+ | Linux / Android / illumos | up to 107 bytes |
71
+ | macOS / iOS / FreeBSD / NetBSD / OpenBSD | up to 103 bytes |
72
+
73
+ A longer path is tried on the routes below, in this order per OS, and bound / connected on the first route that can be used.
74
+
75
+ | OS | Order tried |
76
+ |---|---|
77
+ | Linux / Android (`/proc` usable) | /proc |
78
+ | Linux / Android (`/proc` not usable) | relative path → symlink → thread cwd |
79
+ | FreeBSD | bindat |
80
+ | macOS / iOS | relative path → widened sockaddr → symlink → thread cwd |
81
+ | NetBSD / OpenBSD / illumos / other Unix | relative path → symlink |
82
+ | Windows | not supported (`ImportError` on import) |
83
+
84
+ | Route | How |
85
+ |---|---|
86
+ | /proc | open the directory and pass `/proc/self/fd/<fd>/<file name>` |
87
+ | bindat | `bindat(2)` / `connectat(2)`, by the file name relative to the directory fd |
88
+ | relative path | pass the path relative to the cwd. Only the string is rewritten; the cwd is never changed |
89
+ | widened sockaddr | pass a sockaddr carrying up to 253 bytes, which the macOS kernel accepts |
90
+ | symlink | create a short symlink under `TMPDIR` or `/tmp`, go through it, and remove it at once. It is created only in a place where no other user can replace it |
91
+ | thread cwd | move the cwd of a throwaway thread alone into the directory and pass the file name. The process's cwd is never changed |
92
+ | fork | **none** (the specification's fork route is not built. Neither are the specification's `connect_any` variants) |
93
+
94
+ - None of the routes changes the calling process's cwd, so they can be used from multi-threaded programs
95
+ - A path that fits no route gets `ENAMETOOLONG` (an `OSError` with errno), as a path too long for the standard library does
96
+ - On macOS / Linux, where the thread cwd route can be used, a path is reached at any depth as long as the file name is within 253 bytes (107 on Linux). Linux cannot use the thread cwd route under a seccomp filter (docker's default, for example)
97
+ - The length limits of each route, and where a path stops being reached, are in [docs/MANUAL.md](./docs/MANUAL.md#how-a-long-path-is-reached)
98
+
99
+ ## What differs from the standard library for a long path
100
+
101
+ - `getsockname()` / `getpeername()` do not return the original path: they return the spelling handed to the kernel at bind time (a relative path, `/proc/self/fd/...`, a path through a symlink that no longer exists, the file name alone, ...). Keep the original path yourself
102
+ - A path too long for the standard library that does not end with a name (ending in `dir/`, `dir/.`, `..`) is a `ValueError`
103
+ - A path containing a NUL anywhere but at its start is a `ValueError` at any length (the standard library silently truncates at the NUL). On Linux a path starting with a NUL (abstract namespace) is handed to the standard library unchanged
104
+ - The rest (the directory being looked up first, a symlink that may be left behind) is in [docs/MANUAL.md](./docs/MANUAL.md#what-differs-from-the-standard-library-for-a-long-path)
105
+
106
+ ## asyncio
107
+
108
+ ```python
109
+ listener = sockat.bind(path)
110
+ server = await asyncio.start_unix_server(handle, sock=listener)
111
+
112
+ reader, writer = await asyncio.open_unix_connection(sock=sockat.connect_nonblocking(path))
113
+ ```
114
+
115
+ ## Documentation
116
+
117
+ - [docs/MANUAL.md](./docs/MANUAL.md) — usage, the routes in detail, what differs from the standard library, errors
118
+ - [docs/decisions/](./docs/decisions/INDEX.md) — design decisions (DRs, in Japanese)
119
+
120
+ ## License
121
+
122
+ MIT License, Yoshiaki Kawazu (@kawaz)
@@ -0,0 +1,9 @@
1
+ sockat/__init__.py,sha256=W7ZSvK2UlpxZEy2DpNHd6s-Ka56Af3yX6knRwCwVlVw,2739
2
+ sockat/_path.py,sha256=OVN8gK3WGdoHwirlNRaF-8hilL2cagLiGZbEK60ysZc,3897
3
+ sockat/_route.py,sha256=vS7xP1zg-rc6A9SACMMLlSmdCXUuZxfZBi0YC5SrBNk,30130
4
+ sockat/_sys.py,sha256=LiM9SRUdQ-7nYZq_hmvn2V6EnsRux5D2a2jmBnCNlIY,8970
5
+ sockat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ sockat-0.1.1.dist-info/licenses/LICENSE,sha256=Nn1tFCak4RzMGSlaevNmQdEJIr-Rl4wJohIuAd6n6NA,1081
7
+ sockat-0.1.1.dist-info/WHEEL,sha256=G_-rrEibZr7OEM7zdH1dSO6s-VdjfnS5PA4CLAdI9Vw,80
8
+ sockat-0.1.1.dist-info/METADATA,sha256=s8oynv4R9-AFKshJvT-xXLnTumi_O6_nPloqVQm-YK0,6610
9
+ sockat-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.9
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Yoshiaki Kawazu (@kawaz)
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.