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 +70 -0
- sockat/_path.py +95 -0
- sockat/_route.py +766 -0
- sockat/_sys.py +247 -0
- sockat/py.typed +0 -0
- sockat-0.1.1.dist-info/METADATA +122 -0
- sockat-0.1.1.dist-info/RECORD +9 -0
- sockat-0.1.1.dist-info/WHEEL +4 -0
- sockat-0.1.1.dist-info/licenses/LICENSE +21 -0
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,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.
|