worktree-shield 0.1.0__py3-none-any.whl

worktree_shield/overlap.py

@@ -0,0 +1,175 @@
+"""Whether two resource keys of the same kind name the same resource.
+
+Keys keep what the configuration says (``tcp://*:5173``, ``tcp://127.0.0.1:5173``), so
+equal strings are not the test: two listeners on the same port collide when one of
+them binds every address. The rules here are the ones the collision graph uses.
+
+Ports
+    ``*`` (no host configured) and ``0.0.0.0`` bind every IPv4 address; ``::`` binds every
+    address, IPv4 included, because Linux sockets are dual-stack by default
+    (``net.ipv6.bindv6only = 0``). Two different addresses never collide; a host name
+    *possibly* matches an address or another name, since it is resolved at start-up.
+Databases
+    ``localhost``, ``127.0.0.1`` and ``::1`` reach the same server. A database left to the
+    default (``local``, no host) or a Unix socket is *possibly* that server, and an
+    unknown database name (``?``) possibly any database on it.
+Paths
+    Compared after normalising ``.``, ``..`` and repeated separators, case-insensitively
+    for Windows paths. One inside the other possibly overlaps (an output directory that
+    holds another worktree's cache).
+Names
+    Compose projects, container names and volumes are equal or not.
+
+Client endpoints never overlap: many clients share one server.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import ntpath
+import posixpath
+import re
+from enum import Enum
+
+from worktree_shield.models import ResourceKind
+
+
+class Overlap(Enum):
+    """``SAME`` resource for certain, ``POSSIBLE`` depending on what a name resolves to
+    or how a path is used, or ``NONE``."""
+
+    NONE = "none"
+    POSSIBLE = "possible"
+    SAME = "same"
+
+
+_PORT_KEY = re.compile(r"([a-z]+)://(\[[^\]]*\]|[^:\[\]]*):([0-9]+)")
+_LOOPBACK = frozenset({"localhost", "127.0.0.1", "::1"})
+_LOCAL = "local"
+_IP = ipaddress.IPv4Address | ipaddress.IPv6Address
+
+
+def overlap(kind: ResourceKind, a: str, b: str) -> Overlap:
+    """How the resources behind keys ``a`` and ``b`` (both of ``kind``) overlap."""
+    if kind is ResourceKind.CLIENT_ENDPOINT:
+        return Overlap.NONE
+    if kind is ResourceKind.LISTEN_PORT:
+        return _ports(a, b)
+    if kind is ResourceKind.DATABASE:
+        return _databases(a, b)
+    if kind is ResourceKind.ABSOLUTE_PATH:
+        return _paths(a, b)
+    return Overlap.SAME if a == b else Overlap.NONE
+
+
+def _ports(a: str, b: str) -> Overlap:
+    first, second = _PORT_KEY.fullmatch(a), _PORT_KEY.fullmatch(b)
+    if first is None or second is None:
+        return Overlap.SAME if a == b else Overlap.NONE
+    if (first.group(1), first.group(3)) != (second.group(1), second.group(3)):
+        return Overlap.NONE  # another protocol or port
+    return _hosts(first.group(2).strip("[]"), second.group(2).strip("[]"))
+
+
+def _hosts(a: str, b: str) -> Overlap:
+    if a == b:
+        return Overlap.SAME
+    first, second = _address(a), _address(b)
+    if _binds_all(first, second) or _binds_all(second, first):
+        return Overlap.SAME
+    if isinstance(first, _IP) and isinstance(second, _IP):
+        return Overlap.NONE  # two distinct addresses
+    if "localhost" in (a, b):
+        other = second if a == "localhost" else first
+        if isinstance(other, _IP):
+            return Overlap.POSSIBLE if other.is_loopback else Overlap.NONE
+    return Overlap.POSSIBLE  # a host name: it resolves only when the server starts
+
+
+def _binds_all(this: _IP | str, other: _IP | str) -> bool:
+    """Whether a listener on ``this`` also takes ``other``'s address."""
+    if this == "*" or this == ipaddress.ip_address("::"):
+        return True
+    ipv4_any = ipaddress.ip_address("0.0.0.0")  # noqa: S104
+    return this == ipv4_any and (other == "*" or isinstance(other, ipaddress.IPv4Address))
+
+
+def _address(host: str) -> _IP | str:
+    if host in {"", "*"}:
+        return "*"
+    try:
+        return ipaddress.ip_address(host)
+    except ValueError:
+        return host
+
+
+def _databases(a: str, b: str) -> Overlap:
+    first, second = _database(a), _database(b)
+    if first is None or second is None:
+        return Overlap.SAME if a == b else Overlap.NONE
+    if first[0] != second[0] or first[2] != second[2]:
+        return Overlap.NONE  # another engine or port
+    if first[0] == "sqlite":
+        return Overlap.SAME if first[3] == second[3] else Overlap.NONE
+    server = _servers(first[1], second[1])
+    if server is Overlap.NONE:
+        return server
+    if first[3] == "?" or second[3] == "?":
+        return Overlap.POSSIBLE
+    if first[3] != second[3]:
+        return Overlap.NONE
+    return server
+
+
+def _database(key: str) -> tuple[str, str, str, str] | None:
+    """``db://engine/server:port/database`` as (engine, server, port, database)."""
+    if not key.startswith("db://"):
+        return None
+    engine, _, rest = key[len("db://") :].partition("/")
+    if engine == "sqlite":
+        return engine, "", "", posixpath.normpath(rest)
+    address, _, database = rest.rpartition("/")
+    server, colon, port = address.rpartition(":")
+    if not colon or not port.isdigit():
+        server, port = address, ""
+    return engine, server.strip("[]") if server.startswith("[") else server, port, database
+
+
+def _servers(a: str, b: str) -> Overlap:
+    if a == b or (a in _LOOPBACK and b in _LOOPBACK):
+        return Overlap.SAME
+    if a.startswith("unix:") and b.startswith("unix:"):
+        return Overlap.NONE  # two socket directories, two servers
+    if _is_local(a) and _is_local(b):
+        return Overlap.POSSIBLE  # the default local server, by socket or by TCP
+    return Overlap.NONE
+
+
+def _is_local(server: str) -> bool:
+    return server == _LOCAL or server in _LOOPBACK or server.startswith("unix:")
+
+
+def _paths(a: str, b: str) -> Overlap:
+    first, second = _path(a), _path(b)
+    if first == second:
+        return Overlap.SAME
+    separator = "\\" if "\\" in first or "\\" in second else "/"
+    if first.startswith(second.rstrip(separator) + separator) or second.startswith(
+        first.rstrip(separator) + separator
+    ):
+        return Overlap.POSSIBLE
+    return Overlap.NONE
+
+
+def _path(key: str) -> str:
+    path = key.removeprefix("path://")
+    if re.match(r"[A-Za-z]:[\\/]", path):
+        return ntpath.normcase(ntpath.normpath(path))
+    return posixpath.normpath(path)
+
+
+def path_within(key: str, directory: str) -> bool:
+    """Whether the path of ``key`` (``path://…``) is ``directory`` or lies inside it."""
+    path, root = _path(key), _path(f"path://{directory}")
+    separator = "\\" if "\\" in path or "\\" in root else "/"
+    return path == root or path.startswith(root.rstrip(separator) + separator)

worktree_shield/parsers/__init__.py

@@ -0,0 +1 @@
+"""Parsers for configuration text: pure functions, no file or process access."""

worktree_shield/parsers/commands.py

@@ -0,0 +1,158 @@
+"""Literal listen ports in script command lines, found by reading the text.
+
+Nothing is run or expanded. A command is split like a POSIX shell would split it,
+cut at ``&&``, ``||``, ``;``, ``|`` and ``&``, and each part is searched for the
+spellings dev servers use: ``--port 5173``, ``-p 3001``, ``-l 5000``,
+``--bind 127.0.0.1:8000``, ``-S localhost:8000``, ``PORT=4000 node …`` and the
+argument of ``runserver`` or ``http.server``. Quoted arguments that are commands
+themselves (``concurrently 'vite --port 5173' …``) are searched too.
+
+A port given through a variable (``--port $PORT``) is not literal and is skipped; the
+variable's own definition is where the collectors find it. In a part that runs a client
+(``psql -p 5432``, ``ssh -p 2222``) the flags name a server to connect to and are
+ignored.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from worktree_shield.models import ResourceKind
+from worktree_shield.names import literal_host, port_number, port_variable
+
+_SEPARATORS = frozenset({"&&", "||", ";", "|", "&", ";;", "(", ")"})
+_PORT_FLAGS = frozenset({"--port", "-p", "--listen", "-l"})
+_BIND_FLAGS = frozenset({"--bind", "-b", "-S"})
+_HOST_FLAGS = frozenset({"--host", "--hostname", "-H"})
+_PORT_ARGUMENT_AFTER = frozenset({"runserver", "http.server"})
+_CLIENT_PROGRAMS = frozenset(
+    {
+        "psql",
+        "pg_dump",
+        "pg_restore",
+        "pg_isready",
+        "mysql",
+        "mysqldump",
+        "mysqladmin",
+        "redis-cli",
+        "mongosh",
+        "mongo",
+        "ssh",
+        "scp",
+        "sftp",
+        "nc",
+        "telnet",
+        "curl",
+        "wget",
+        "docker",
+        "podman",
+        "kubectl",
+    }
+)
+_VARIABLE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_MAX_DEPTH = 3
+
+
+@dataclass(frozen=True, slots=True)
+class PortMention:
+    """A listen port in a command; ``fragment`` is the part that names it (never the
+    whole command, which may carry other values). ``strict`` is set for Vite: ``True``
+    with ``--strictPort``, otherwise ``False`` (it moves to the next free port)."""
+
+    port: int
+    host: str | None
+    fragment: str
+    strict: bool | None = None
+
+
+def listen_ports(command: str) -> list[PortMention]:
+    """Every literal listen port in ``command``, in order."""
+    return _scan(command, 0)
+
+
+def _scan(command: str, depth: int) -> list[PortMention]:
+    found: list[PortMention] = []
+    part: list[str] = []
+    for token in [*_tokens(command), ";"]:
+        if token in _SEPARATORS:
+            found += _scan_part(part, depth)
+            part = []
+        else:
+            part.append(token)
+    return found
+
+
+def _tokens(command: str) -> list[str]:
+    lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+    lexer.whitespace_split = True
+    lexer.commenters = ""
+    try:
+        return list(lexer)
+    except ValueError:  # an unclosed quote: words are still worth a look
+        return command.split()
+
+
+def _scan_part(part: list[str], depth: int) -> list[PortMention]:
+    if any(PurePosixPath(token).name in _CLIENT_PROGRAMS for token in part):
+        return []
+    strict = None
+    if any(PurePosixPath(token).name == "vite" for token in part):
+        strict = "--strictPort" in part or "--strict-port" in part
+    host = _host_option(part)
+    found: list[PortMention] = []
+    for index, token in enumerate(part):
+        following = part[index + 1] if index + 1 < len(part) else None
+        if any(c.isspace() for c in token):
+            if depth < _MAX_DEPTH:
+                found += _scan(token, depth + 1)
+            continue
+        name, equals, value = token.partition("=")
+        if equals and _VARIABLE.fullmatch(name):
+            port = port_number(value)
+            if port is not None and port_variable(name) is ResourceKind.LISTEN_PORT:
+                found.append(PortMention(port, None, token, None))
+            continue
+        argument: str | None
+        if equals and name.startswith("-"):
+            flag, argument, fragment = name, value, token
+        else:
+            flag, argument, fragment = token, following, f"{token} {following}"
+        if argument is None:
+            continue
+        if flag in _PORT_FLAGS:
+            port = port_number(argument)
+            if port is not None:
+                found.append(PortMention(port, host, fragment, strict))
+        elif flag in _BIND_FLAGS or flag in _PORT_ARGUMENT_AFTER:
+            address = _address(argument)
+            if address is not None:
+                found.append(PortMention(address[1], address[0], fragment, strict))
+    return found
+
+
+def _host_option(part: list[str]) -> str | None:
+    for index, token in enumerate(part):
+        name, equals, value = token.partition("=")
+        if equals and name in _HOST_FLAGS:
+            return literal_host(value)
+        if token in _HOST_FLAGS and index + 1 < len(part):
+            return literal_host(part[index + 1])
+    return None
+
+
+def _address(text: str) -> tuple[str | None, int] | None:
+    """``127.0.0.1:8000``, ``[::1]:8000``, ``:8000`` or ``8000`` as host and port."""
+    host_text, colon, port_text = text.rpartition(":")
+    if not colon:
+        port = port_number(text)
+        return (None, port) if port is not None else None
+    port = port_number(port_text)
+    if port is None:
+        return None
+    if not host_text:
+        return None, port
+    host = literal_host(host_text)
+    return (host, port) if host is not None else None

worktree_shield/parsers/compose.py

@@ -0,0 +1,148 @@
+"""The ``ports`` and ``volumes`` syntax of the Compose specification.
+
+Only what decides a collision is extracted: the host ports a service publishes (two
+stacks publishing the same host port cannot run at once) and the host paths and named
+volumes it mounts. Values must already be interpolated. An entry that is not valid
+Compose comes back as ``None`` so a report can say it was not understood, rather than
+as a guess.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from worktree_shield.names import literal_host, port_number
+
+MAX_RANGE = 256  # ports in one published range; a wider one is reported as unreadable
+_PROTOCOLS = frozenset({"tcp", "udp", "sctp"})
+_RANGE = re.compile(r"([0-9]{1,5})(?:-([0-9]{1,5}))?")
+_WINDOWS_SOURCE = re.compile(r"[A-Za-z]:[\\/]")
+
+
+@dataclass(frozen=True, slots=True)
+class PublishedPort:
+    """A host port a service publishes. ``host_ip`` is as written (``0.0.0.0`` stays);
+    ``None`` means no address was given, which also publishes on every address."""
+
+    host_ip: str | None
+    port: int
+    protocol: str = "tcp"
+
+
+@dataclass(frozen=True, slots=True)
+class Mount:
+    """One entry of a service's ``volumes``. ``source`` is a host path for ``bind``, a
+    volume name for ``volume`` (``None`` for an anonymous one), ``None`` for ``tmpfs``."""
+
+    kind: str
+    source: str | None
+    read_only: bool = False
+
+
+def published_ports(entry: Any) -> list[PublishedPort] | None:
+    """The host ports a ``ports`` entry publishes: empty when Docker picks a free one,
+    ``None`` when the entry is not valid."""
+    if isinstance(entry, bool):
+        return None
+    if isinstance(entry, int):
+        return [] if port_number(str(entry)) is not None else None
+    if isinstance(entry, str):
+        return _short_ports(entry.strip())
+    if isinstance(entry, dict):
+        return _long_ports(entry)
+    return None
+
+
+def _short_ports(text: str) -> list[PublishedPort] | None:
+    """``[[IP:]HOST:]CONTAINER[/PROTOCOL]``, ports or ranges, IPv6 in brackets."""
+    text, _, protocol = text.partition("/")
+    protocol = protocol or "tcp"
+    if protocol not in _PROTOCOLS:
+        return None
+    host_ip: str | None = None
+    if text.startswith("["):
+        address, bracket, text = text[1:].partition("]")
+        if not bracket or not text.startswith(":"):
+            return None
+        host_ip, text = literal_host(address), text[1:]
+        if host_ip is None:
+            return None
+    parts = text.split(":")
+    if len(parts) == 3 and host_ip is None:
+        host_ip = literal_host(parts[0])
+        if host_ip is None:
+            return None
+        parts = parts[1:]
+    if len(parts) == 1:
+        return [] if _ports(parts[0]) else None  # container port only
+    if len(parts) != 2 or _ports(parts[1]) is None:
+        return None
+    if parts[0] == "":
+        return []  # 127.0.0.1::5000: a free host port on that address
+    host_ports = _ports(parts[0])
+    if host_ports is None:
+        return None
+    return [PublishedPort(host_ip, port, protocol) for port in host_ports]
+
+
+def _long_ports(entry: dict[str, Any]) -> list[PublishedPort] | None:
+    published = entry.get("published")
+    if published is None:
+        return [] if "target" in entry else None
+    if isinstance(published, bool) or not isinstance(published, (int, str)):
+        return None
+    host_ports = _ports(str(published))
+    protocol = entry.get("protocol", "tcp")
+    host_ip = entry.get("host_ip")
+    if host_ports is None or protocol not in _PROTOCOLS:
+        return None
+    if host_ip is not None and (not isinstance(host_ip, str) or literal_host(host_ip) is None):
+        return None
+    address = literal_host(host_ip) if isinstance(host_ip, str) else None
+    return [PublishedPort(address, port, protocol) for port in host_ports]
+
+
+def _ports(text: str) -> list[int] | None:
+    """``8000`` or ``8000-8005`` as a list of ports; ``None`` if not valid."""
+    match = _RANGE.fullmatch(text)
+    if match is None:
+        return None
+    first = port_number(match.group(1))
+    last = port_number(match.group(2)) if match.group(2) else first
+    if first is None or last is None or last < first or last - first >= MAX_RANGE:
+        return None
+    return list(range(first, last + 1))
+
+
+def parse_mount(entry: Any) -> Mount | None:
+    """One ``volumes`` entry of a service, short or long syntax; ``None`` if not valid."""
+    if isinstance(entry, str):
+        return _short_mount(entry.strip())
+    if isinstance(entry, dict):
+        kind = entry.get("type", "volume")
+        source = entry.get("source")
+        if not isinstance(kind, str) or (source is not None and not isinstance(source, str)):
+            return None
+        if kind == "bind" and not source:
+            return None
+        return Mount(kind, source or None, entry.get("read_only") is True)
+    return None
+
+
+def _short_mount(text: str) -> Mount | None:
+    """``[SOURCE:]TARGET[:MODE]``; a source that looks like a path is a bind mount."""
+    if not text:
+        return None
+    drive = ""
+    if _WINDOWS_SOURCE.match(text):
+        drive, text = text[:2], text[2:]
+    parts = text.split(":")
+    if len(parts) == 1:
+        return Mount("volume", None) if not drive else None  # anonymous volume
+    source, mode = drive + parts[0], parts[2] if len(parts) > 2 else ""
+    read_only = "ro" in mode.split(",")
+    if drive or source.startswith(("/", ".", "~")):
+        return Mount("bind", source, read_only)
+    return Mount("volume", source, read_only)

worktree_shield/parsers/dburl.py

@@ -0,0 +1,156 @@
+"""Database URLs reduced to what identifies the database: engine, server and name.
+
+User names and passwords are dropped while parsing; they reach neither the result nor
+an error message, and an error never repeats the URL. When the server cannot be found
+with certainty (an unencoded ``/``, ``?`` or ``#`` in a password moves the apparent
+host, a libpq host list, an unexpanded ``${DB_HOST}``) the URL is refused with
+:class:`DatabaseURLError` instead of being guessed: a wrong host would report a
+collision that is not there, or hide one that is.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from urllib.parse import parse_qs, unquote
+
+_SCHEME = re.compile(r"(?:jdbc:)?([A-Za-z][A-Za-z0-9+.-]*)://(.*)", re.S)
+_ENGINES = {
+    "postgres": "postgres",
+    "postgresql": "postgres",
+    "mysql": "mysql",
+    "mariadb": "mysql",
+    "redis": "redis",
+    "rediss": "redis",
+    "mongodb": "mongodb",
+    "sqlite": "sqlite",
+}
+_DEFAULT_PORTS = {"postgres": 5432, "mysql": 3306, "redis": 6379, "mongodb": 27017}
+_REFERENCE = re.compile(r"\$(?:\{|[A-Za-z_])")
+_BRACKETED = re.compile(r"\[([^\]]*)\](?::(.*))?")
+_DIGITS = re.compile(r"[0-9]{1,5}")  # str.isdigit() also accepts "²", which int() refuses
+
+
+class DatabaseURLError(ValueError):
+    """A database URL whose server cannot be determined safely; never contains the URL."""
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseTarget:
+    """A database without credentials. ``host`` is lower case, ``None`` for the local
+    default or a Unix ``socket``; ``port`` is the engine's default when not given;
+    ``database`` is ``None`` when the URL leaves it to the server (Postgres then uses
+    the user name, which was dropped). For SQLite ``database`` is the file path."""
+
+    engine: str
+    host: str | None
+    port: int | None
+    database: str | None
+    socket: str | None = None
+
+    @property
+    def key(self) -> str:
+        """``db://postgres/localhost:5432/app_dev``: equal keys, same database."""
+        if self.engine == "sqlite":
+            return f"db://sqlite/{self.database}"
+        if self.socket is not None:
+            server = f"unix:{self.socket}"
+        elif self.host is None:
+            server = "local"
+        elif ":" in self.host and "," not in self.host:
+            server = f"[{self.host}]"
+        else:
+            server = self.host
+        port = "" if self.port is None else f":{self.port}"
+        database = self.database if self.database is not None else "?"
+        return f"db://{self.engine}/{server}{port}/{database}"
+
+
+def parse_database_url(value: str) -> DatabaseTarget | None:
+    """The database ``value`` points to, or ``None`` when it is not a database URL.
+
+    Raises :class:`DatabaseURLError` for a database URL that cannot be read safely.
+    """
+    match = _SCHEME.fullmatch(value.strip())
+    if match is None:
+        return None
+    scheme, rest = match.group(1).lower(), match.group(2)
+    engine = _ENGINES.get(scheme.split("+", 1)[0])
+    if engine is None:
+        return None
+    if engine == "sqlite":
+        return _sqlite(rest)
+    if _REFERENCE.search(rest):
+        raise DatabaseURLError("it refers to another variable, which is not expanded")
+    end = min((i for i in (rest.find(c) for c in "/?#") if i >= 0), default=len(rest))
+    authority, tail = rest[:end], rest[end:]
+    if "@" in tail:
+        raise DatabaseURLError(
+            "it has an @ after the host part, so an unencoded /, ? or # in the password "
+            "may have moved the host; percent-encode the password"
+        )
+    hostport = authority.rsplit("@", 1)[-1]  # everything before the last @ is credentials
+    path, _, query_part = tail.partition("#")[0].partition("?")
+    query = parse_qs(query_part)
+    database = unquote(path.lstrip("/")) or None
+    if engine == "mongodb":
+        return _mongodb(hostport, database, srv=scheme == "mongodb+srv")
+    if "," in hostport:
+        raise DatabaseURLError("it lists several hosts")
+    host, port = _host_and_port(hostport, _DEFAULT_PORTS[engine])
+    socket = None
+    if engine == "postgres":
+        host = _host(_first(query, "host", host))
+        port = _port(_first(query, "port", None), port)
+        database = _first(query, "dbname", database)
+    if engine == "redis":
+        database = _first(query, "db", database) or "0"
+    if host is not None and host.startswith("/"):
+        host, socket = None, host
+    return DatabaseTarget(engine, host, port, database, socket)
+
+
+def _sqlite(rest: str) -> DatabaseTarget | None:
+    path = unquote(rest.partition("?")[0].removeprefix("/"))
+    if not path or path == ":memory:":
+        return None  # in memory: nothing on disk to share
+    return DatabaseTarget("sqlite", None, None, path)
+
+
+def _mongodb(hostport: str, database: str | None, *, srv: bool) -> DatabaseTarget:
+    default = None if srv else _DEFAULT_PORTS["mongodb"]
+    servers = [_host_and_port(part, default) for part in hostport.split(",")]
+    if len(servers) == 1:
+        host, port = servers[0]
+        return DatabaseTarget("mongodb", host, port, database)
+    names = sorted(f"{host}:{port}" if port is not None else f"{host}" for host, port in servers)
+    return DatabaseTarget("mongodb", ",".join(names), None, database)
+
+
+def _host_and_port(hostport: str, default: int | None) -> tuple[str | None, int | None]:
+    bracketed = _BRACKETED.fullmatch(hostport)
+    if bracketed is not None:
+        host, port = bracketed.group(1), bracketed.group(2)
+    else:
+        host, _, port = hostport.partition(":")
+    return _host(unquote(host)), _port(port or None, default)
+
+
+def _host(name: str | None) -> str | None:
+    """Host names are case-insensitive; a socket path (``/run/postgresql``) is not."""
+    if not name:
+        return None
+    return name if name.startswith("/") else name.lower()
+
+
+def _port(text: str | None, default: int | None) -> int | None:
+    if text is None:
+        return default
+    if not _DIGITS.fullmatch(text) or not 1 <= int(text) <= 65535:
+        raise DatabaseURLError("its port is not a number from 1 to 65535")
+    return int(text)
+
+
+def _first(query: dict[str, list[str]], name: str, default: str | None) -> str | None:
+    values = query.get(name)
+    return values[0] if values else default