beam-lan 0.1.0__py3-none-any.whl

beam/__init__.py

@@ -0,0 +1,31 @@
+"""beam - zip a project and send it to another laptop, anywhere.
+
+    import beam
+
+    code = beam.send("D:/projects/my_app", exclude=[".mp4", ".log"])  # laptop A
+    beam.receive(code)                                               # laptop B
+
+    beam.send("D:/projects/my_app", lan=True)   # direct, same Wi-Fi only
+    beam.pack("D:/projects/my_app")             # only make my_app.zip
+
+The zip carries a start.bat that installs what the project needs and runs it.
+"""
+
+__version__ = "0.1.0"  # before the imports: _cloud reads it for its User-Agent
+
+from ._files import DEFAULT_EXCLUDES  # noqa: E402
+from ._protocol import DEFAULT_PORT, BeamError, find_sender, lan_ip  # noqa: E402
+from .packer import pack  # noqa: E402
+from .transfer import receive, send  # noqa: E402
+
+__all__ = [
+    "send",
+    "receive",
+    "pack",
+    "find_sender",
+    "lan_ip",
+    "BeamError",
+    "DEFAULT_EXCLUDES",
+    "DEFAULT_PORT",
+    "__version__",
+]

beam/_cloud.py

@@ -0,0 +1,187 @@
+"""Free temporary file hosts that carry the encrypted zip between laptops.
+
+Each host is tried in order. The code starts with the host's letter, so the
+receiver knows where to download from.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import urllib.error
+import urllib.request
+
+from . import __version__
+from ._protocol import BeamError
+
+USER_AGENT = f"beam-lan/{__version__} (+https://pypi.org/project/beam-lan/)"
+UPLOAD_NAME = "beam.bin"
+BLOCK = 1 << 16
+
+
+class _Host:
+    letter = ""
+    label = ""
+    max_bytes = 0
+    keeps = ""
+
+    def upload(self, path, progress) -> str:
+        """Upload ``path`` and return the host's id for it."""
+        raise NotImplementedError
+
+    def download_request(self, file_id) -> urllib.request.Request:
+        raise NotImplementedError
+
+
+class TempSh(_Host):
+    letter, label, max_bytes, keeps = "t", "temp.sh", 4 * 1024**3, "3 days"
+
+    def upload(self, path, progress):
+        url = _post_file("https://temp.sh/upload", "file", path, progress).strip()
+        # https://temp.sh/<id>/beam.bin
+        parts = url.rstrip("/").split("/")
+        if len(parts) < 2 or not url.startswith("https://temp.sh/"):
+            raise BeamError(f"temp.sh gave an unexpected reply: {url[:100]!r}")
+        return parts[-2]
+
+    def download_request(self, file_id):
+        # temp.sh serves the file itself only to a POST; a GET returns a page.
+        return urllib.request.Request(
+            f"https://temp.sh/{file_id}/{UPLOAD_NAME}", data=b"", method="POST"
+        )
+
+
+class Uguu(_Host):
+    letter, label, max_bytes, keeps = "u", "uguu.se", 128 * 1024**2, "3 hours"
+
+    def upload(self, path, progress):
+        reply = _post_file("https://uguu.se/upload", "files[]", path, progress)
+        try:
+            url = json.loads(reply)["files"][0]["url"]
+        except (ValueError, KeyError, IndexError, TypeError):
+            raise BeamError(
+                f"uguu.se gave an unexpected reply: {reply[:100]!r}"
+            ) from None
+        # https://<server>.uguu.se/<name>.bin - the server letter varies
+        prefix = "https://"
+        server, _, name = url[len(prefix) :].partition(".uguu.se/")
+        if not url.startswith(prefix) or not name.endswith(".bin") or "/" in name:
+            raise BeamError(f"uguu.se gave an unexpected reply: {url[:100]!r}")
+        return f"{server}.{name[: -len('.bin')]}"
+
+    def download_request(self, file_id):
+        server, _, name = file_id.partition(".")
+        return urllib.request.Request(f"https://{server}.uguu.se/{name}.bin")
+
+
+HOSTS = [TempSh(), Uguu()]
+BY_LETTER = {host.letter: host for host in HOSTS}
+
+
+class _MultipartBody:
+    """File-like multipart/form-data body, streamed from disk with progress."""
+
+    def __init__(self, field, path, progress):
+        self.boundary = "beam" + secrets.token_hex(16)
+        self.head = (
+            f"--{self.boundary}\r\n"
+            f'Content-Disposition: form-data; name="{field}"; '
+            f'filename="{UPLOAD_NAME}"\r\n'
+            "Content-Type: application/octet-stream\r\n\r\n"
+        ).encode()
+        self.tail = f"\r\n--{self.boundary}--\r\n".encode()
+        self.size = os.path.getsize(path)
+        self.length = len(self.head) + self.size + len(self.tail)
+        self.fh = open(path, "rb")
+        self.stage = 0
+        self.sent = 0
+        self.progress = progress
+
+    def read(self, n=-1):
+        if self.stage == 0:
+            self.stage = 1
+            return self.head
+        if self.stage == 1:
+            data = self.fh.read(BLOCK if n is None or n < 0 else n)
+            if data:
+                self.sent += len(data)
+                if self.progress:
+                    self.progress(self.sent, self.size)
+                return data
+            self.stage = 2
+            return self.tail
+        return b""
+
+    def close(self):
+        self.fh.close()
+
+
+def _post_file(url, field, path, progress) -> str:
+    body = _MultipartBody(field, path, progress)
+    request = urllib.request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": f"multipart/form-data; boundary={body.boundary}",
+            "Content-Length": str(body.length),
+            "User-Agent": USER_AGENT,
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=120) as resp:
+            return resp.read(1 << 16).decode("utf-8", "replace")
+    finally:
+        body.close()
+
+
+def upload(path, progress=None, say=None) -> tuple[str, str, str]:
+    """Upload to the first host that takes it. Returns (letter, file_id, keeps)."""
+    size = os.path.getsize(path)
+    errors = []
+    for host in HOSTS:
+        if size > host.max_bytes:
+            errors.append(f"{host.label}: file is over its size limit")
+            continue
+        if say:
+            say(f"  uploading to {host.label} ...")
+        try:
+            return host.letter, host.upload(path, progress), host.keeps
+        except (OSError, BeamError) as exc:  # URLError is an OSError
+            errors.append(f"{host.label}: {exc}")
+            if say:
+                say(f"\n  {host.label} failed ({exc}), trying the next one")
+    raise BeamError("upload failed on every host:\n    " + "\n    ".join(errors))
+
+
+def download(letter, file_id, dst, progress=None) -> None:
+    host = BY_LETTER.get(letter)
+    if host is None:
+        raise BeamError(
+            "this code is not valid (unknown host); check it was copied fully"
+        )
+    request = host.download_request(file_id)
+    request.add_header("User-Agent", USER_AGENT)
+    try:
+        with urllib.request.urlopen(request, timeout=120) as resp:
+            total = int(resp.headers.get("Content-Length") or 0)
+            done = 0
+            with open(dst, "wb") as fh:
+                for block in iter(lambda: resp.read(BLOCK), b""):
+                    fh.write(block)
+                    done += len(block)
+                    if progress:
+                        progress(done, total)
+    except urllib.error.HTTPError as exc:
+        if exc.code in (404, 410):
+            raise BeamError(
+                f"nothing found for this code on {host.label}: it has expired "
+                f"(kept for {host.keeps}) or was mistyped"
+            ) from None
+        raise BeamError(f"download failed: {host.label} said {exc.code}") from None
+    except urllib.error.URLError as exc:
+        raise BeamError(
+            f"could not reach {host.label} ({exc.reason}); "
+            "check the internet connection"
+        ) from None

beam/_crypto.py

@@ -0,0 +1,93 @@
+"""Encrypting a file before it leaves the laptop, and decrypting it on arrival.
+
+AES-256-GCM over 1 MiB chunks. Each chunk's nonce carries its index and a
+"last chunk" flag, so reordered, dropped or truncated chunks fail to decrypt.
+The key comes from the secret half of the code, which never reaches the host.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import struct
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from ._protocol import BeamError
+
+MAGIC = b"BEAM\x01"
+CHUNK = 1 << 20
+
+
+def _key(secret: str, salt: bytes) -> bytes:
+    return hmac.new(secret.encode(), b"beam-v1" + salt, hashlib.sha256).digest()
+
+
+def _nonce(prefix: bytes, index: int, last: bool) -> bytes:
+    return prefix + struct.pack("!IB", index, int(last))
+
+
+def encrypt_file(src, dst, secret: str, meta: dict, progress=None) -> None:
+    """Write ``src`` to ``dst`` encrypted; ``meta`` (e.g. the filename) rides along."""
+    salt, prefix = os.urandom(16), os.urandom(7)
+    aes = AESGCM(_key(secret, salt))
+    total = os.path.getsize(src)
+    done = 0
+    with open(src, "rb") as fin, open(dst, "wb") as fout:
+        fout.write(MAGIC + salt + prefix)
+        blob = aes.encrypt(_nonce(prefix, 0, False), json.dumps(meta).encode(), None)
+        fout.write(struct.pack("!BI", 0, len(blob)) + blob)
+        index = 1
+        block = fin.read(CHUNK)
+        while True:
+            nxt = fin.read(CHUNK) if len(block) == CHUNK else b""
+            last = not nxt
+            blob = aes.encrypt(_nonce(prefix, index, last), block, None)
+            fout.write(struct.pack("!BI", int(last), len(blob)) + blob)
+            done += len(block)
+            if progress:
+                progress(done, total)
+            if last:
+                break
+            block, index = nxt, index + 1
+
+
+def decrypt_file(src, dst, secret: str) -> dict:
+    """Decrypt ``src`` into ``dst``; return the metadata stored with it."""
+    wrong = BeamError("could not decrypt: wrong code, or the file was damaged")
+    with open(src, "rb") as fin:
+        head = fin.read(len(MAGIC) + 16 + 7)
+        if not head.startswith(MAGIC) or len(head) < len(MAGIC) + 23:
+            raise BeamError("this download is not a beam file (expired or wrong code?)")
+        salt, prefix = head[5:21], head[21:28]
+        aes = AESGCM(_key(secret, salt))
+
+        def chunk(index):
+            raw = fin.read(5)
+            if len(raw) < 5:
+                raise BeamError("download is incomplete; try again")
+            last, size = struct.unpack("!BI", raw)
+            if size > CHUNK + 16:
+                raise wrong
+            data = fin.read(size)
+            try:
+                return bool(last), aes.decrypt(
+                    _nonce(prefix, index, bool(last)), data, None
+                )
+            except InvalidTag:
+                raise wrong from None
+
+        _, meta_raw = chunk(0)
+        meta = json.loads(meta_raw)
+        with open(dst, "wb") as fout:
+            index, last = 1, False
+            while not last:
+                last, data = chunk(index)
+                fout.write(data)
+                index += 1
+        if fin.read(1):
+            raise wrong
+    return meta

beam/_files.py

@@ -0,0 +1,125 @@
+"""Walking the project tree, exclude rules, hashing."""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import os
+from pathlib import Path
+
+HASH_CHUNK = 1 << 20
+
+# Things you almost never want to carry between machines: virtualenvs are
+# platform-specific, caches are regenerable, .git is better cloned, .env
+# usually holds secrets.
+DEFAULT_EXCLUDES = [
+    ".git",
+    ".hg",
+    ".svn",
+    "__pycache__",
+    "*.pyc",
+    "*.pyo",
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    "*.egg-info",
+    "node_modules",
+    ".DS_Store",
+    "Thumbs.db",
+]
+
+
+def human(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} GB"
+
+
+def normalize_excludes(exclude) -> list[str]:
+    """Turn user-friendly excludes into glob patterns.
+
+    ".mp4", "mp4" and "*.mp4" all skip mp4 files. A bare name like "data" or
+    ".cache" also skips a file or folder with exactly that name.
+    """
+    if exclude is None:
+        return []
+    if isinstance(exclude, (str, os.PathLike)):
+        exclude = [exclude]
+    patterns = []
+    for item in exclude:
+        item = str(item).strip().replace("\\", "/")
+        if not item:
+            continue
+        if any(ch in item for ch in "*?[/"):
+            patterns.append(item)
+        else:
+            patterns.append(item)
+            patterns.append("*." + item.lstrip("."))
+    return patterns
+
+
+def excluded(rel: Path, patterns) -> bool:
+    text = rel.as_posix()
+    for pat in patterns:
+        pat = pat.rstrip("/")
+        if fnmatch.fnmatch(rel.name, pat):
+            return True
+        if any(fnmatch.fnmatch(part, pat) for part in rel.parts):
+            return True
+        if fnmatch.fnmatch(text, pat):
+            return True
+    return False
+
+
+def read_ignore_file(root: Path) -> list:
+    """Read .beamignore if present. Simple glob patterns, one per line."""
+    path = root / ".beamignore"
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            out.append(line)
+    return out
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for block in iter(lambda: fh.read(HASH_CHUNK), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def walk(root: Path, patterns, max_bytes=None):
+    """Return ([(abs_path, rel_path, size)], [(rel_path, size)]) - kept, skipped."""
+    found, skipped = [], []
+    for dirpath, dirnames, filenames in os.walk(root):
+        here = Path(dirpath)
+        rel_dir = here.relative_to(root)
+        dirnames[:] = sorted(d for d in dirnames if not excluded(rel_dir / d, patterns))
+        for name in sorted(filenames):
+            rel = rel_dir / name
+            if excluded(rel, patterns):
+                continue
+            abs_path = here / name
+            if abs_path.is_symlink() and not abs_path.exists():
+                continue  # broken symlink
+            try:
+                size = abs_path.stat().st_size
+            except OSError:
+                continue
+            if max_bytes is not None and size > max_bytes:
+                skipped.append((rel, size))
+                continue
+            found.append((abs_path, rel, size))
+    return found, skipped

beam/_protocol.py

@@ -0,0 +1,161 @@
+"""Wire protocol: framing, errors, and network helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import socket
+import struct
+import threading
+import time
+
+PROTOCOL = 2
+DEFAULT_PORT = 8765
+DISCOVERY_PORT = 8766
+MAX_HEADER = 1024 * 1024
+
+
+class BeamError(RuntimeError):
+    """The other side refused us, or the stream was malformed."""
+
+
+def send_msg(sock: socket.socket, obj: dict) -> None:
+    raw = json.dumps(obj).encode("utf-8")
+    sock.sendall(struct.pack("!I", len(raw)) + raw)
+
+
+def recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = bytearray()
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            raise BeamError("connection closed mid-message")
+        buf += chunk
+    return bytes(buf)
+
+
+def recv_msg(sock: socket.socket) -> dict:
+    (length,) = struct.unpack("!I", recv_exact(sock, 4))
+    if length > MAX_HEADER:
+        raise BeamError("refusing an absurdly large header")
+    return json.loads(recv_exact(sock, length).decode("utf-8"))
+
+
+def lan_ip() -> str:
+    """Best guess at this machine's address on the local network."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect(("8.8.8.8", 80))  # no packets are actually sent
+        return sock.getsockname()[0]
+    except OSError:
+        return "127.0.0.1"
+    finally:
+        sock.close()
+
+
+# --- discovery ---------------------------------------------------------------
+#
+# The receiver only knows the code. It broadcasts a UDP query carrying a hash
+# of the code; the sender with that code answers with its TCP port, and the
+# reply's source address tells the receiver where to connect.
+
+
+def code_tag(code: str) -> str:
+    return hashlib.sha256(f"beam:{code}".encode()).hexdigest()[:16]
+
+
+def _local_ipv4s() -> set[str]:
+    ips = {lan_ip()}
+    try:
+        for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            ips.add(info[4][0])
+    except OSError:
+        pass
+    return {ip for ip in ips if not ip.startswith("127.")}
+
+
+def _broadcast_targets() -> list[str]:
+    targets = ["255.255.255.255", "127.0.0.1"]
+    # Windows often sends 255.255.255.255 out of one adapter only, so also hit
+    # each adapter's subnet broadcast (assuming the usual home /24).
+    for ip in _local_ipv4s():
+        targets.append(ip.rsplit(".", 1)[0] + ".255")
+    return targets
+
+
+class DiscoveryResponder:
+    """Answers discovery queries for one code until stopped."""
+
+    def __init__(
+        self, code: str, port: int, name: str, udp_port: int = DISCOVERY_PORT
+    ):
+        self.tag = code_tag(code)
+        self.reply = json.dumps(
+            {"beam": PROTOCOL, "id": self.tag, "port": port, "name": name}
+        ).encode("utf-8")
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.sock.bind(("", udp_port))
+        self.sock.settimeout(0.5)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> DiscoveryResponder:
+        self._thread.start()
+        return self
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                data, addr = self.sock.recvfrom(2048)
+                query = json.loads(data.decode("utf-8"))
+            except (OSError, ValueError):  # timeout, ICMP reset, junk
+                continue
+            if isinstance(query, dict) and query.get("find") == self.tag:
+                try:
+                    self.sock.sendto(self.reply, addr)
+                except OSError:
+                    pass
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2)
+        self.sock.close()
+
+
+def find_sender(
+    code: str, timeout: float = 15.0, udp_port: int = DISCOVERY_PORT
+) -> tuple[str, int, str]:
+    """Locate the sender holding ``code`` on the LAN. Returns (host, port, name)."""
+    tag = code_tag(code)
+    query = json.dumps({"beam": PROTOCOL, "find": tag}).encode("utf-8")
+    targets = _broadcast_targets()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    sock.bind(("", 0))
+    sock.settimeout(0.3)
+    deadline = time.monotonic() + timeout
+    next_ping = 0.0
+    try:
+        while time.monotonic() < deadline:
+            if time.monotonic() >= next_ping:
+                for target in targets:
+                    try:
+                        sock.sendto(query, (target, udp_port))
+                    except OSError:
+                        pass
+                next_ping = time.monotonic() + 1.0
+            try:
+                data, addr = sock.recvfrom(2048)
+                reply = json.loads(data.decode("utf-8"))
+            except (OSError, ValueError):
+                continue
+            if isinstance(reply, dict) and reply.get("id") == tag:
+                return addr[0], int(reply["port"]), str(reply.get("name", ""))
+    finally:
+        sock.close()
+    raise BeamError(
+        f"no sender with code {code!r} found on this network after {timeout:.0f}s "
+        "(same Wi-Fi? firewall allowing Python? or pass host=IP)"
+    )