zapchat 3.0.0__py3-none-any.whl

zapchat/__init__.py

@@ -0,0 +1,3 @@
+"""zapchat: terminal-native LAN chat with no accounts and no server."""
+
+__version__ = "3.0.0"

zapchat/cli.py

@@ -0,0 +1,332 @@
+"""Command line entry point: `zapchat` starts a terminal chat session.
+
+The chat loop is deliberately simple line-based I/O so it works everywhere
+(Windows cmd, PowerShell, ssh, tmux): what you type is sent, what others say
+is printed. Type /help to see the commands.
+"""
+
+import argparse
+import os
+import sys
+import threading
+import time
+import uuid
+
+from .client import ChatClient
+from .discovery import DiscoveryService, DISCOVERY_PORT
+from .protocol import (
+    MAX_USERNAME_LENGTH,
+    sanitize_room_name,
+    sanitize_username,
+)
+from . import __version__
+
+CONFIG_DIR_ENV = "ZAPCHAT_CONFIG_DIR"
+DEFAULT_ROOM = "general"
+
+
+def default_username():
+    """OS account name when it is usable, otherwise a random handle."""
+    try:
+        account = os.getlogin()
+    except OSError:
+        account = os.environ.get("USERNAME") or os.environ.get("USER") or ""
+    username = sanitize_username(account)
+    if username:
+        return username
+    return "zapper-" + uuid.uuid4().hex[:4]
+
+
+def config_path():
+    """Path of the tiny local config file (username + client id)."""
+    override = os.environ.get(CONFIG_DIR_ENV)
+    if override:
+        directory = override
+    elif sys.platform == "win32":
+        directory = os.path.join(os.environ.get("APPDATA", os.path.expanduser("~")), "zapchat")
+    elif sys.platform == "darwin":
+        directory = os.path.join(os.path.expanduser("~"), "Library", "Application Support", "zapchat")
+    else:
+        directory = os.path.join(
+            os.environ.get("XDG_CONFIG_HOME", os.path.join(os.path.expanduser("~"), ".config")),
+            "zapchat",
+        )
+    return os.path.join(directory, "config.json")
+
+
+def load_or_create_config(name_override=None):
+    """Read the config file, creating it when missing. Never fatal."""
+    import json
+
+    path = config_path()
+    config = {"clientId": "zpy-" + uuid.uuid4().hex, "username": "", "lastRoom": DEFAULT_ROOM}
+
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            stored = json.load(handle)
+        if isinstance(stored, dict):
+            if isinstance(stored.get("clientId"), str) and stored["clientId"]:
+                config["clientId"] = stored["clientId"]
+            if isinstance(stored.get("username"), str):
+                config["username"] = stored["username"]
+            if isinstance(stored.get("lastRoom"), str):
+                config["lastRoom"] = stored["lastRoom"]
+    except (OSError, ValueError):
+        pass
+
+    if name_override:
+        config["username"] = name_override
+
+    if not sanitize_username(config["username"]):
+        config["username"] = default_username()
+
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(config, handle, indent=2)
+    except OSError:
+        pass
+
+    return config
+
+
+class ChatApp:
+    """Wires discovery + the TCP client together and runs the chat loop."""
+
+    def __init__(self, username, room, client_id, no_discovery=False, connect_to=None):
+        self.username = username
+        self.room = room
+        self.client_id = client_id
+        self.no_discovery = no_discovery
+        self.connect_to = connect_to
+
+        self.history = []  # rendered lines kept for /help-style local commands
+        self.lock = threading.Lock()
+        self.connected_usernames = set()
+
+        self.chat = ChatClient(
+            client_id,
+            username,
+            get_room=lambda: self.room,
+            on_event=self._on_event,
+        )
+
+        self.discovery = None
+        if not no_discovery:
+            self.discovery = DiscoveryService(
+                client_id,
+                username,
+                room,
+                tcp_port=0,  # set after the TCP port is bound
+                on_warning=lambda message: self._print(f"! {message}"),
+            )
+
+    # ------------------------------------------------------------------ events
+
+    def _on_event(self, kind, **kwargs):
+        if kind == "message":
+            # Envelope timestamps are in milliseconds; localtime wants seconds.
+            ts = kwargs.get("ts")
+            seconds = (ts / 1000) if isinstance(ts, (int, float)) and ts > 10_000_000_000 else time.time()
+            stamp = time.strftime("%H:%M", time.localtime(seconds))
+            self._print(f"{stamp} {kwargs['sender']}: {kwargs['text']}")
+        elif kind == "peer-connected":
+            self._print(f"* {kwargs['username']} connected")
+        elif kind == "peer-gone":
+            self._print(f"* {kwargs['username']} left")
+        elif kind == "warning":
+            self._print(f"! {kwargs['text']}")
+
+    def _print(self, line):
+        with self.lock:
+            sys.stdout.write(line + "\n")
+            sys.stdout.flush()
+
+    # ------------------------------------------------------------------- start
+
+    def start(self):
+        port = self.chat.start()
+        if self.discovery is not None:
+            self.discovery.tcp_port = port
+            self.discovery.start()
+            self.discovery.set_state(self.username, self.room, port)
+
+        self._print(f"zapchat {__version__} — LAN chat, no accounts, no server")
+        self._print(f"  you are {self.username} on #{self.room} (tcp:{port})")
+        if self.no_discovery:
+            self._print("  discovery off; use /connect <ip> to reach a peer")
+        else:
+            self._print("  waiting for people on this network... (ctrl+c to quit, /help)")
+
+        if self.connect_to:
+            address, _, port_text = self.connect_to.partition(":")
+            self.chat.connect_to(address, int(port_text or 45913))
+
+        threading.Thread(target=self._dial_loop, daemon=True).start()
+        threading.Thread(target=self._heartbeat_loop, daemon=True).start()
+
+    def _heartbeat_loop(self):
+        """PING every peer periodically so half-open links get reaped."""
+        while self.chat._running:
+            time.sleep(5.0)
+            try:
+                self.chat.send_heartbeat()
+            except Exception:  # never let the heartbeat die
+                pass
+
+    def _dial_loop(self):
+        """Connect to discovered peers we are not already linked to.
+
+        Only the instance with the lexicographically smaller client id dials,
+        so two instances never dial each other at the same moment and the
+        link never gets duplicated (same rule as the npm client).
+        """
+        while self.chat._running:
+            if self.discovery is not None:
+                for peer in self.discovery.live_peers():
+                    should_dial = (
+                        peer.client_id not in self.chat.peer_ids
+                        and peer.client_id < self.client_id
+                    )
+                    if should_dial:
+                        peer._source = self.discovery._beacon_sources.get(peer.client_id)
+                        self.chat.connect_to_peer_object(peer)
+            time.sleep(1.0)
+
+    def stop(self):
+        if self.discovery is not None:
+            self.discovery.stop()
+        self.chat.stop()
+
+    # -------------------------------------------------------------- chat loop
+
+    def handle_line(self, line):
+        """Process one input line: a /command or chat to send."""
+        if line.startswith("/"):
+            self.run_command(line)
+            return
+
+        if not self.chat.peer_ids:
+            self._print("! nobody is connected yet; waiting for the network...")
+            return
+        self.chat.send_chat(line)
+
+    def run_command(self, line):
+        parts = line[1:].split(maxsplit=1)
+        command = parts[0].lower() if parts else ""
+        argument = parts[1].strip() if len(parts) > 1 else ""
+
+        if command in ("help", "h", "?"):
+            self._print(
+                "commands: /rooms /users /join <room> /name <username> "
+                "/connect <ip[:port]> /status /quit"
+            )
+        elif command == "rooms":
+            rooms = self.discovery.live_rooms() if self.discovery else {}
+            if self.room:
+                rooms.setdefault(self.room, {"online": 1, "seen": 0})
+            for name, info in sorted(rooms.items()):
+                self._print(f"  #{name}  {info['online']} online")
+            if not rooms:
+                self._print("  no rooms discovered yet")
+        elif command in ("users", "who"):
+            if self.discovery is not None:
+                for peer in self.discovery.live_peers():
+                    room = f"  #{peer.room}" if peer.room else ""
+                    self._print(f"  {peer.username}{room}")
+            for client_id in self.chat.peer_ids:
+                self._print(f"  {client_id} (connected)")
+        elif command == "join":
+            room = sanitize_room_name(argument)
+            if not room:
+                self._print("! usage: /join <room>")
+                return
+            self.room = room
+            if self.discovery is not None:
+                self.discovery.set_state(self.username, room, self.chat.port)
+            self._print(f"* joined #{room}")
+        elif command == "name":
+            name = sanitize_username(argument)
+            if not name:
+                self._print("! usage: /name <username>")
+                return
+            self.username = name
+            if self.discovery is not None:
+                self.discovery.set_state(name, self.room, self.chat.port)
+            self._print(f"* you are now {name}")
+        elif command == "connect":
+            address, _, port_text = argument.partition(":")
+            if not address:
+                self._print("! usage: /connect <ip[:port]>")
+                return
+            threading.Thread(
+                target=self.chat.connect_to,
+                args=(address, int(port_text or 45913)),
+                daemon=True,
+            ).start()
+        elif command == "status":
+            discovery = self.discovery
+            if discovery is None:
+                self._print("  discovery: off")
+            else:
+                self._print(
+                    f"  discovery: {'multicast' if discovery.multicast_ok else 'broadcast'}"
+                    f" on udp:{DISCOVERY_PORT}, {discovery.beacons_sent} sent,"
+                    f" {discovery.beacons_received} received"
+                )
+            self._print(f"  tcp port: {self.chat.port}, peers: {len(self.chat.peer_ids)}")
+        elif command in ("quit", "q", "exit"):
+            raise KeyboardInterrupt
+        else:
+            self._print(f"! unknown command /{command}; try /help")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="zapchat",
+        description="Terminal-native LAN chat. No accounts, no cloud, no servers.",
+    )
+    parser.add_argument("-n", "--name", help="display name (remembered between runs)")
+    parser.add_argument("-r", "--room", help="room to join on start")
+    parser.add_argument("-c", "--connect", metavar="HOST[:PORT]", help="connect straight to a peer")
+    parser.add_argument("--discovery-port", type=int, default=DISCOVERY_PORT, help="UDP discovery port")
+    parser.add_argument("--tcp-port", type=int, default=45913, help="first TCP port to try")
+    parser.add_argument("--no-discovery", action="store_true", help="manual connections only")
+    parser.add_argument("-v", "--version", action="version", version=f"zapchat {__version__}")
+    args = parser.parse_args(argv)
+
+    config = load_or_create_config(name_override=args.name)
+    room = sanitize_room_name(args.room) if args.room else None
+    if room is None and args.room:
+        parser.error("room names may only contain letters, digits, - and _")
+    if room is None:
+        room = sanitize_room_name(config.get("lastRoom")) or DEFAULT_ROOM
+
+    app = ChatApp(
+        username=config["username"],
+        room=room,
+        client_id=config["clientId"],
+        no_discovery=args.no_discovery,
+        connect_to=args.connect,
+    )
+
+    app.start()
+
+    # Standard input is line-buffered; ctrl+c raises KeyboardInterrupt.
+    try:
+        for line in sys.stdin:
+            line = line.strip()
+            if line:
+                try:
+                    app.handle_line(line)
+                except KeyboardInterrupt:
+                    break
+    except KeyboardInterrupt:
+        pass
+
+    app.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

zapchat/client.py

@@ -0,0 +1,337 @@
+"""The LAN chat client: a TCP mesh between discovered instances.
+
+Wire-compatible with the npm client's protocol v1: newline-delimited JSON
+envelopes over TCP, HELLO handshake, room-scoped MESSAGE frames with
+duplicate suppression and a one-hop relay so a message still lands when two
+peers are not directly connected to each other.
+"""
+
+import socket
+import threading
+
+from .protocol import (
+    create_envelope,
+    decode_frames,
+    encode_envelope,
+    now_ms,
+    parse_envelope,
+    sanitize_room_name,
+)
+
+MAX_PEERS = 64
+DEDUP_CACHE_SIZE = 1024
+
+
+class ChatClient:
+    """Owns the listening TCP socket and every peer link."""
+
+    def __init__(self, client_id, username, get_room, on_event=None):
+        """`get_room` is read fresh for every HELLO (the room can change)."""
+        self.client_id = client_id
+        self.username = username
+        self.get_room = get_room
+        self.on_event = on_event or (lambda kind, **kwargs: None)
+
+        self._server = None
+        self._server_port = 0
+        self._running = False
+        self._lock = threading.RLock()
+
+        # client_id -> {"socket": Socket, "username": str, "room": str|None}
+        self._links = {}
+        # message ids we have already seen (duplicate suppression)
+        self._seen_ids = set()
+        self._seen_order = []
+
+    # ------------------------------------------------------------------ setup
+
+    def start(self, port_base=45913, attempts=12):
+        """Bind a listening socket, trying port_base and the next few ports.
+
+        No SO_REUSEADDR: on Windows it would let two instances silently share
+        the port and split incoming connections. A busy port just moves us to
+        the next candidate, which is exactly what the npm client does.
+        """
+        import sys
+
+        self._running = True
+        for offset in range(attempts):
+            try:
+                self._server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                if sys.platform != "win32":
+                    self._server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                self._server.bind(("0.0.0.0", port_base + offset))
+                self._server.listen(16)
+                self._server_port = port_base + offset
+                break
+            except OSError:
+                self._server.close()
+                self._server = None
+
+        if self._server is None:
+            # Ephemeral fallback so a fully busy range still works.
+            self._server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self._server.bind(("0.0.0.0", 0))
+            self._server.listen(16)
+            self._server_port = self._server.getsockname()[1]
+
+        threading.Thread(target=self._accept_loop, daemon=True).start()
+        return self._server_port
+
+    def stop(self):
+        self._running = False
+        if self._server is not None:
+            try:
+                self._server.close()
+            except OSError:
+                pass
+            self._server = None
+        with self._lock:
+            for link in list(self._links.values()):
+                try:
+                    link["socket"].close()
+                except OSError:
+                    pass
+            self._links.clear()
+
+    @property
+    def port(self):
+        return self._server_port
+
+    @property
+    def peer_ids(self):
+        with self._lock:
+            return list(self._links.keys())
+
+    # ------------------------------------------------------------- connecting
+
+    def connect_to(self, address, port, timeout=3.0):
+        """Dial a peer and run the HELLO handshake. Returns True on success."""
+        try:
+            sock = socket.create_connection((address, port), timeout=timeout)
+        except OSError as error:
+            self.on_event("warning", text=f"could not connect to {address}:{port} ({error})")
+            return False
+
+        sock.settimeout(5.0)
+        hello = self._build_hello()
+        try:
+            sock.sendall(encode_envelope(hello))
+            reply = self._read_envelopes(sock)
+        except OSError:
+            sock.close()
+            return False
+
+        peer_envelope = next((e for e in reply if e["type"] == "HELLO"), None)
+        if peer_envelope is None or peer_envelope["from"] == self.client_id:
+            sock.close()
+            return False
+
+        with self._lock:
+            if peer_envelope["from"] in self._links or len(self._links) >= MAX_PEERS:
+                sock.close()
+                return False
+
+            self._links[peer_envelope["from"]] = {
+                "socket": sock,
+                "username": peer_envelope["username"],
+                "room": peer_envelope["room"],
+            }
+
+        # The handshake timeout must not linger: an idle chat link is healthy,
+        # and a leftover recv timeout would drop it every few seconds.
+        sock.settimeout(None)
+
+        threading.Thread(target=self._serve_link, args=(sock, peer_envelope["from"]), daemon=True).start()
+        self.on_event("peer-connected", client_id=peer_envelope["from"], username=peer_envelope["username"])
+        return True
+
+    def connect_to_peer_object(self, peer):
+        """Dial a discovery.Peer, trying its advertised addresses in turn."""
+        candidates = list(peer.addresses)
+        source = getattr(peer, "_source", None)
+        if source and source not in candidates:
+            candidates.append(source)
+        for address in candidates:
+            if self.connect_to(address, peer.port):
+                return True
+        return False
+
+    # ---------------------------------------------------------------- sending
+
+    def send_chat(self, text):
+        """Send a message to every connected peer in the same room."""
+        room = self.get_room()
+        envelope = create_envelope("MESSAGE", self.client_id, self.username, room=room, data={"text": text})
+        sent = self._broadcast(envelope, room)
+        self.on_event("message-sent", envelope=envelope, peers=sent)
+        return sent
+
+    def send_heartbeat(self):
+        self._broadcast(create_envelope("PING", self.client_id, self.username), None)
+
+    # ------------------------------------------------------------- internals
+
+    def _build_hello(self):
+        return create_envelope(
+            "HELLO",
+            self.client_id,
+            self.username,
+            room=self.get_room(),
+            data={"port": self._server_port, "addresses": []},
+        )
+
+    def _read_envelopes(self, sock, initial=""):
+        """Read from the socket until a newline-delimited envelope arrives."""
+        buffer = initial
+        envelopes = []
+        try:
+            while not envelopes:
+                chunk = sock.recv(4096)
+                if not chunk:
+                    break
+                envelopes, buffer = decode_frames(chunk, buffer)
+        except OSError:
+            pass
+        return envelopes
+
+    def _accept_loop(self):
+        while self._running:
+            try:
+                sock, address = self._server.accept()
+            except OSError:
+                return
+            threading.Thread(target=self._serve_inbound, args=(sock, address), daemon=True).start()
+
+    def _serve_inbound(self, sock, address):
+        sock.settimeout(5.0)
+        try:
+            envelopes = self._read_envelopes(sock)
+        except OSError:
+            sock.close()
+            return
+
+        hello = next((e for e in envelopes if e["type"] == "HELLO"), None)
+        if hello is None or hello["from"] == self.client_id:
+            sock.close()
+            return
+
+        with self._lock:
+            if hello["from"] in self._links or len(self._links) >= MAX_PEERS:
+                sock.close()
+                return
+            self._links[hello["from"]] = {
+                "socket": sock,
+                "username": hello["username"],
+                "room": hello["room"],
+            }
+
+        # Reply with our own HELLO so both ends are identified.
+        try:
+            sock.sendall(encode_envelope(self._build_hello()))
+        except OSError:
+            self._drop_link(hello["from"])
+            return
+
+        sock.settimeout(None)
+        self.on_event("peer-connected", client_id=hello["from"], username=hello["username"])
+        self._serve_link(sock, hello["from"])
+
+    def _serve_link(self, sock, client_id):
+        buffer = ""
+        while self._running:
+            try:
+                chunk = sock.recv(8192)
+            except (OSError, TimeoutError):
+                break
+            if not chunk:
+                break
+            envelopes, buffer = decode_frames(chunk, buffer)
+            for envelope in envelopes:
+                self._handle(envelope, client_id)
+
+        self._drop_link(client_id)
+
+    def _handle(self, envelope, client_id):
+        if envelope["id"] in self._seen_ids:
+            return
+        self._remember_id(envelope["id"])
+
+        msg_type = envelope["type"]
+        if msg_type == "PONG":
+            return
+        if msg_type == "PING":
+            self._send_to(client_id, create_envelope("PONG", self.client_id, self.username))
+            return
+        if msg_type == "HELLO":
+            with self._lock:
+                link = self._links.get(client_id)
+                if link is not None:
+                    link["username"] = envelope["username"]
+                    link["room"] = envelope["room"]
+            return
+
+        if msg_type == "MESSAGE":
+            text = envelope["data"].get("text") if isinstance(envelope["data"], dict) else None
+            if text:
+                self.on_event(
+                    "message",
+                    sender=envelope["username"],
+                    text=text,
+                    room=envelope["room"],
+                    client_id=envelope["from"],
+                    ts=envelope["ts"],
+                )
+            # One-hop relay: forward to same-room peers that have not seen it.
+            self._relay(envelope, from_client=client_id)
+        elif msg_type in ("JOIN", "LEAVE", "ANNOUNCE"):
+            self.on_event("presence", envelope=envelope)
+
+    def _remember_id(self, message_id):
+        self._seen_ids.add(message_id)
+        self._seen_order.append(message_id)
+        if len(self._seen_order) > DEDUP_CACHE_SIZE:
+            for old in self._seen_order[:-DEDUP_CACHE_SIZE]:
+                self._seen_ids.discard(old)
+            del self._seen_order[:-DEDUP_CACHE_SIZE]
+
+    def _relay(self, envelope, from_client):
+        """Forward a room-scoped frame to other same-room peers (once)."""
+        self._broadcast(envelope, envelope["room"], skip_client=from_client)
+
+    def _broadcast(self, envelope, room, skip_client=None):
+        """Send to every peer in `room` (all peers when room is None)."""
+        sent = 0
+        with self._lock:
+            targets = [
+                (cid, link["socket"])
+                for cid, link in self._links.items()
+                if cid != skip_client and (room is None or link["room"] == room)
+            ]
+        for client_id, sock in targets:
+            if self._send_to(client_id, envelope, sock=sock):
+                sent += 1
+        return sent
+
+    def _send_to(self, client_id, envelope, sock=None):
+        with self._lock:
+            link = self._links.get(client_id)
+            sock = sock or (link["socket"] if link else None)
+        if sock is None:
+            return False
+        try:
+            sock.sendall(encode_envelope(envelope))
+            return True
+        except OSError:
+            self._drop_link(client_id)
+            return False
+
+    def _drop_link(self, client_id):
+        with self._lock:
+            link = self._links.pop(client_id, None)
+        if link is not None:
+            try:
+                link["socket"].close()
+            except OSError:
+                pass
+            self.on_event("peer-gone", client_id=client_id, username=link["username"])

zapchat/discovery.py

@@ -0,0 +1,289 @@
+"""UDP discovery: announce ourselves, listen for other instances.
+
+Compatible with the npm client: the same multicast group and port, the same
+ANNOUNCE envelope shape, beacons sent to multicast, subnet broadcast and
+loopback so several instances work on one machine too.
+"""
+
+import json
+import socket
+import sys
+import threading
+
+from .protocol import (
+    MAX_UDP_PACKET_BYTES,
+    MAX_USERNAME_LENGTH,
+    create_envelope,
+    now_ms,
+    parse_announce_data,
+    parse_envelope,
+)
+
+MULTICAST_GROUP = "239.255.42.99"
+DISCOVERY_PORT = 45912
+ANNOUNCE_INTERVAL = 2.0
+PEER_STALE_SECONDS = 7
+
+
+class Peer:
+    """Another instance seen on the LAN."""
+
+    def __init__(self, client_id, username, room, port, addresses, last_seen):
+        self.client_id = client_id
+        self.username = username
+        self.room = room
+        self.port = port
+        self.addresses = addresses
+        self.last_seen = last_seen
+
+    def fresh(self, now=None):
+        return now_ms() - self.last_seen < PEER_STALE_SECONDS * 1000
+
+
+class DiscoveryService:
+    """Bind one UDP socket, send beacons, and keep a map of live peers."""
+
+    def __init__(self, client_id, username, room, tcp_port, on_warning=None):
+        self.client_id = client_id
+        self.username = username
+        self.room = room
+        self.tcp_port = tcp_port
+        self.on_warning = on_warning or (lambda message: None)
+
+        self.peers = {}  # client_id -> Peer
+        self.rooms = {}  # room name -> {"online": int, "seen": ms}
+        self.beacons_sent = 0
+        self.beacons_received = 0
+        self.multicast_ok = False
+        self.broadcast_ok = False
+
+        self._sock = None
+        self._running = False
+        self._lock = threading.Lock()
+        self._beacon_sources = {}  # client_id -> (ip, port) of last beacon
+        self._owns_discovery_port = False
+        self._replied_to = set()  # client ids we have unicast-replied to
+
+    # ------------------------------------------------------------------ state
+
+    def current_room(self):
+        return self.room
+
+    def set_state(self, username, room, tcp_port):
+        """Update what our beacons advertise (called on any identity change)."""
+        self.username = username
+        self.room = room
+        self.tcp_port = tcp_port
+
+    def live_peers(self):
+        """Fresh peers only, stale entries pruned."""
+        now = now_ms()
+        with self._lock:
+            for client_id in [cid for cid, p in self.peers.items() if not p.fresh(now)]:
+                del self.peers[client_id]
+            return list(self.peers.values())
+
+    def live_rooms(self):
+        """Rooms advertised by anyone (including us), freshest counts win."""
+        with self._lock:
+            for peer in self.peers.values():
+                if peer.fresh() and peer.room:
+                    entry = self.rooms.setdefault(peer.room, {"online": 0, "seen": 0})
+                    entry["seen"] = max(entry["seen"], peer.last_seen)
+        return dict(self.rooms)
+
+    # ----------------------------------------------------------------- socket
+
+    def start(self):
+        self._running = True
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            if sys.platform != "win32":
+                # On POSIX, REUSEADDR allows quick restarts and multi-process
+                # multicast. On Windows it would let a second bind "succeed"
+                # while unicast then reaches only the last binder — so there
+                # we deliberately let the second bind fail and fall back.
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind(("", DISCOVERY_PORT))
+                self._owns_discovery_port = True
+            except OSError:
+                # Another instance owns the well-known port. Multicast (joined
+                # below) still delivers to every member regardless of bind
+                # port, which is what keeps several instances on one machine
+                # working.
+                sock.bind(("", 0))
+                self.on_warning("another instance holds the discovery port; using multicast")
+
+            self._sock = sock
+
+            try:
+                group = socket.inet_aton(MULTICAST_GROUP)
+                mreq = group + socket.inet_aton("0.0.0.0")
+                sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+                self.multicast_ok = True
+            except OSError:
+                self.on_warning("multicast unavailable; falling back to broadcast")
+
+            try:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+                self.broadcast_ok = True
+            except OSError:
+                pass
+
+            threading.Thread(target=self._listen, daemon=True).start()
+            threading.Thread(target=self._announce_loop, daemon=True).start()
+            self.send_beacon()
+        except OSError as error:
+            self.on_warning(f"discovery unavailable: {error}")
+
+    def stop(self):
+        self._running = False
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+            self._sock = None
+
+    # ---------------------------------------------------------------- sending
+
+    def beacon_targets(self):
+        """Where beacons go: multicast, each subnet broadcast, and loopback."""
+        targets = []
+        if self.multicast_ok:
+            targets.append((MULTICAST_GROUP, DISCOVERY_PORT))
+
+        # Loopback unicast only helps when we (or a same-machine peer) own the
+        # well-known port; the multicast path covers the other same-machine
+        # instances.
+        targets.append(("127.0.0.1", DISCOVERY_PORT))
+
+        for address in self._local_addresses():
+            broadcast = ".".join(address.split(".")[:-1]) + ".255"
+            if broadcast not in [t[0] for t in targets]:
+                targets.append((broadcast, DISCOVERY_PORT))
+
+        if self.broadcast_ok and ("255.255.255.255", DISCOVERY_PORT) not in targets:
+            targets.append(("255.255.255.255", DISCOVERY_PORT))
+
+        return targets
+
+    def _local_addresses(self):
+        """Best-effort list of this machine's LAN IPv4 addresses."""
+        addresses = []
+        try:
+            hostname = socket.gethostname()
+            for info in socket.getaddrinfo(hostname, None, socket.AF_INET):
+                address = info[4][0]
+                if address not in addresses and not address.startswith("127."):
+                    addresses.append(address)
+        except OSError:
+            pass
+        return addresses
+
+    def build_beacon(self):
+        local_port = self._sock.getsockname()[1] if self._sock is not None else 0
+        return create_envelope(
+            "ANNOUNCE",
+            self.client_id,
+            (self.username or "anon")[:MAX_USERNAME_LENGTH],
+            room=self.room,
+            data={
+                "port": self.tcp_port,
+                "addresses": self._local_addresses(),
+                "rooms": [self.room] if self.room else [],
+                # Where a unicast beacon reaches us directly (Python clients).
+                "replyPort": local_port,
+            },
+        )
+
+    def send_beacon(self):
+        if self._sock is None:
+            return
+        packet = json.dumps(self.build_beacon(), separators=(",", ":")).encode("utf-8")[:MAX_UDP_PACKET_BYTES]
+        for target in self.beacon_targets():
+            try:
+                self._sock.sendto(packet, target)
+                self.beacons_sent += 1
+            except OSError as error:
+                self.on_warning(f"beacon to {target[0]} failed: {error}")
+
+    def _announce_loop(self):
+        import time
+
+        while self._running:
+            self.send_beacon()
+            time.sleep(ANNOUNCE_INTERVAL)
+
+    # -------------------------------------------------------------- receiving
+
+    def _listen(self):
+        while self._running:
+            try:
+                packet, address = self._sock.recvfrom(MAX_UDP_PACKET_BYTES * 2)
+            except OSError:
+                return
+
+            try:
+                raw = json.loads(packet.decode("utf-8", errors="replace"))
+            except ValueError:
+                continue
+
+            envelope = parse_envelope(raw)
+            if envelope is None:
+                continue
+
+            # Our own beacon echoing back from a multicast membership: skip it.
+            if envelope["from"] == self.client_id:
+                continue
+
+            data = parse_announce_data(envelope["data"])
+            if data is None:
+                continue
+
+            self.beacons_received += 1
+            self._remember_peer(envelope, data, address)
+
+    def _remember_peer(self, envelope, data, source_address):
+        with self._lock:
+            client_id = envelope["from"]
+            peer = self.peers.get(client_id)
+            if peer is None:
+                peer = Peer(
+                    client_id=client_id,
+                    username=envelope["username"],
+                    room=envelope["room"] or (data["rooms"][0] if data["rooms"] else None),
+                    port=data["port"],
+                    addresses=data["addresses"],
+                    last_seen=now_ms(),
+                )
+            else:
+                peer.username = envelope["username"]
+                peer.room = envelope["room"] or peer.room
+                peer.port = data["port"]
+                if data["addresses"]:
+                    peer.addresses = data["addresses"]
+                peer.last_seen = now_ms()
+
+            self.peers[client_id] = peer
+            # Remember where the beacon came from so TCP can dial it even if
+            # the advertised address list was empty.
+            self._beacon_sources[client_id] = source_address[0]
+
+            for room in data["rooms"] or ([peer.room] if peer.room else []):
+                entry = self.rooms.setdefault(room, {"online": 0, "seen": 0})
+                entry["seen"] = now_ms()
+
+        # First contact: reply by direct unicast so the other side learns us
+        # even when multicast/broadcast is unavailable (the Python protocol
+        # carries a replyPort for exactly this; npm peers ignore it).
+        if client_id not in self._replied_to and data["reply_port"]:
+            self._replied_to.add(client_id)
+            try:
+                if self._sock is not None:
+                    packet = json.dumps(self.build_beacon(), separators=(",", ":")).encode("utf-8")
+                    self._sock.sendto(packet, (source_address[0], data["reply_port"]))
+                    self.beacons_sent += 1
+            except OSError:
+                pass

zapchat/protocol.py

@@ -0,0 +1,256 @@
+"""Wire protocol shared by discovery beacons and TCP messages.
+
+An envelope is a JSON object with routing metadata and a type-specific
+`data` payload. Everything that arrives from the network is untrusted:
+`parse_envelope` returns None for anything that does not match the expected
+shape, and callers simply drop it.
+"""
+
+import json
+import re
+import time
+import uuid
+
+PROTOCOL_VERSION = 1
+
+# The npm client uses these limits; stay compatible.
+MAX_MESSAGE_CHARS = 1000
+MAX_USERNAME_LENGTH = 20
+MAX_ROOM_NAME_LENGTH = 20
+MAX_UDP_PACKET_BYTES = 1100
+MAX_FRAME_BYTES = 8 * 1024
+MAX_CLOCK_SKEW_MS = 10 * 60 * 1000
+
+MESSAGE_TYPES = {
+    "HELLO", "ANNOUNCE", "ROOM_LIST", "PEER_LIST",
+    "JOIN", "LEAVE", "MESSAGE", "PING", "PONG",
+}
+
+ENVELOPE_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
+CLIENT_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{6,64}$")
+USERNAME_PATTERN = re.compile(r"^[a-zA-Z0-9_\-\. ]+$")
+ROOM_PATTERN = re.compile(r"^[a-z0-9][a-z0-9\-_]*$")
+
+# Control characters and C1 range: never allowed in display text.
+CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+# ANSI escape sequences (CSI etc.): strip the whole sequence, not just the
+# ESC byte, so a hostile sender cannot repaint the receiver's terminal.
+ANSI_SEQUENCES = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])")
+
+
+def now_ms():
+    return int(time.time() * 1000)
+
+
+def new_message_id():
+    return str(uuid.uuid4())
+
+
+def sanitize_text(value, max_length):
+    """Strip ANSI sequences and control characters, cap the length."""
+    if not isinstance(value, str):
+        return None
+    cleaned = CONTROL_CHARS.sub("", ANSI_SEQUENCES.sub("", value)).strip()
+    if not cleaned or len(cleaned) > max_length * 2:
+        return None
+    return cleaned[:max_length]
+
+
+def sanitize_username(value):
+    if not isinstance(value, str):
+        return None
+    cleaned = CONTROL_CHARS.sub("", ANSI_SEQUENCES.sub("", value)).strip()[:MAX_USERNAME_LENGTH]
+    if cleaned and USERNAME_PATTERN.match(cleaned):
+        return cleaned
+    return None
+
+
+def sanitize_room_name(value):
+    if not isinstance(value, str):
+        return None
+    cleaned = CONTROL_CHARS.sub("", value).strip().lower()[:MAX_ROOM_NAME_LENGTH]
+    if cleaned and ROOM_PATTERN.match(cleaned):
+        return cleaned
+    return None
+
+
+def is_valid_port(value):
+    return isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= 65535
+
+
+def is_valid_client_id(value):
+    return isinstance(value, str) and CLIENT_ID_PATTERN.match(value) is not None
+
+
+def sanitize_address_list(value, max_addresses=8):
+    """Keep well-formed IPv4 strings, drop everything else."""
+    if not isinstance(value, list):
+        return []
+    kept = []
+    for entry in value[: max_addresses * 2]:
+        if isinstance(entry, str) and re.match(r"^(\d{1,3}\.){3}\d{1,3}$", entry):
+            kept.append(entry)
+        if len(kept) >= max_addresses:
+            break
+    return kept
+
+
+def create_envelope(msg_type, sender_id, username, room=None, data=None, env_id=None, ts=None):
+    """Build an envelope to send. Senders always use this helper."""
+    return {
+        "v": PROTOCOL_VERSION,
+        "id": env_id or new_message_id(),
+        "type": msg_type,
+        "ts": ts if ts is not None else now_ms(),
+        "from": sender_id,
+        "username": username,
+        "room": room,
+        "data": data if data is not None else None,
+    }
+
+
+def _coerce_username(value):
+    """Usernames are display-only: repair rather than reject."""
+    cleaned = sanitize_username(value)
+    if cleaned:
+        return cleaned
+    if isinstance(value, str):
+        stripped = CONTROL_CHARS.sub("", ANSI_SEQUENCES.sub("", value)).strip()[:20]
+        if stripped:
+            return stripped
+    return "unnamed"
+
+
+def _coerce_room(value):
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return sanitize_room_name(value)
+    return False  # invalid: reject the whole envelope
+
+
+def parse_envelope(raw, clock_skew_check=True):
+    """Validate an untrusted value into an envelope dict, or None."""
+    if not isinstance(raw, dict):
+        return None
+    if raw.get("v") != PROTOCOL_VERSION:
+        return None
+
+    env_id = raw.get("id")
+    if not isinstance(env_id, str) or not ENVELOPE_ID_PATTERN.match(env_id):
+        return None
+
+    msg_type = raw.get("type")
+    if msg_type not in MESSAGE_TYPES:
+        return None
+
+    sender = raw.get("from")
+    if not is_valid_client_id(sender):
+        return None
+
+    ts = raw.get("ts")
+    if not isinstance(ts, (int, float)) or isinstance(ts, bool) or ts <= 0:
+        return None
+    if clock_skew_check and abs(now_ms() - ts) > MAX_CLOCK_SKEW_MS:
+        return None
+
+    room = _coerce_room(raw.get("room"))
+    if room is False:
+        return None
+
+    return {
+        "v": PROTOCOL_VERSION,
+        "id": env_id,
+        "type": msg_type,
+        "ts": ts,
+        "from": sender,
+        "username": _coerce_username(raw.get("username")),
+        "room": room,
+        "data": raw.get("data"),
+    }
+
+
+def parse_message_data(data):
+    """Validate a MESSAGE payload; return the text or None."""
+    if not isinstance(data, dict):
+        return None
+    text = data.get("text")
+    if not isinstance(text, str):
+        return None
+    if len(text) > MAX_MESSAGE_CHARS * 4:
+        return None
+    cleaned = CONTROL_CHARS.sub("", ANSI_SEQUENCES.sub("", text)).strip()[:MAX_MESSAGE_CHARS]
+    return cleaned or None
+
+
+def parse_announce_data(data):
+    """Validate an ANNOUNCE/HELLO payload: port, addresses, rooms."""
+    if not isinstance(data, dict):
+        return None
+    port = data.get("port")
+    if not is_valid_port(port):
+        return None
+    addresses = sanitize_address_list(data.get("addresses"))
+
+    # Optional direct-reply port (Python clients): where a unicast beacon can
+    # reach us reliably, immune to multicast outages. The npm client ignores
+    # this extra field.
+    reply_port = data.get("replyPort")
+    if not is_valid_port(reply_port):
+        reply_port = 0
+
+    rooms = []
+    raw_rooms = data.get("rooms")
+    if isinstance(raw_rooms, list):
+        for candidate in raw_rooms:
+            room = sanitize_room_name(candidate) if isinstance(candidate, str) else None
+            if room and room not in rooms:
+                rooms.append(room)
+    return {"port": port, "addresses": addresses, "rooms": rooms, "reply_port": reply_port}
+
+
+def parse_room_list_data(data):
+    """Validate a ROOM_LIST payload into a list of {name, online}."""
+    if not isinstance(data, dict) or not isinstance(data.get("rooms"), list):
+        return None
+    rooms = []
+    for entry in data["rooms"][:128]:
+        if not isinstance(entry, dict) or not isinstance(entry.get("name"), str):
+            continue
+        name = sanitize_room_name(entry["name"])
+        if not name:
+            continue
+        online = entry.get("online")
+        if isinstance(online, int) and not isinstance(online, bool) and 0 <= online <= 1000:
+            rooms.append({"name": name, "online": online})
+        else:
+            rooms.append({"name": name, "online": 0})
+    return {"rooms": rooms}
+
+
+def encode_envelope(envelope):
+    """Serialise one envelope as a TCP frame (JSON plus newline)."""
+    return (json.dumps(envelope, separators=(",", ":")) + "\n").encode("utf-8")
+
+
+def decode_frames(chunk, buffer=""):
+    """Split received bytes into envelopes.
+
+    TCP gives us arbitrary chunks; JSON envelopes are newline-delimited.
+    Returns (envelopes, leftover_bytes_str). Invalid lines are dropped.
+    """
+    text = buffer + chunk.decode("utf-8", errors="replace")
+    envelopes = []
+    while "\n" in text:
+        line, text = text.split("\n", 1)
+        if not line.strip() or len(line) > MAX_FRAME_BYTES:
+            continue
+        try:
+            raw = json.loads(line)
+        except ValueError:
+            continue
+        envelope = parse_envelope(raw)
+        if envelope is not None:
+            envelopes.append(envelope)
+    return envelopes, text

zapchat-3.0.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: zapchat
+Version: 3.0.0
+Summary: Terminal-native LAN chat. No accounts, no cloud, no servers - just your local network.
+Author: Samarth Chugh (Sam3360)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sam3360/zapchatnpm
+Project-URL: Repository, https://github.com/Sam3360/zapchatnpm
+Project-URL: Issues, https://github.com/Sam3360/zapchatnpm/issues
+Keywords: lan,chat,cli,terminal,p2p,udp,discovery,local-network
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# zapchat (Python)
+
+**Terminal-native LAN chat. No accounts, no cloud, no servers — just your
+local network.**
+
+This is the Python distribution of [zapchat](https://github.com/Sam3360/zapchatnpm).
+It speaks the same discovery protocol as the Node.js version, so a Python user
+and an npm user on the same Wi-Fi can chat with each other.
+
+> The Python client runs the proven protocol v1 wire format (JSON envelopes
+> over TCP, signed discovery beacons). The Node.js client's protocol v2 adds
+> TLS-style encryption on top of the same envelope shapes — the Python client
+> interoperates with npm peers via the shared discovery and messaging format.
+
+## Install
+
+```bash
+pip install zapchat
+```
+
+## Run
+
+```bash
+zapchat
+```
+
+That is it. Everyone on the same network who runs `zapchat` shows up
+automatically, and you can start chatting.
+
+```
+zapchat 3.0.0 — LAN chat, no accounts, no server
+  you are sam on #general (tcp:45913)
+  waiting for people on this network... (ctrl+c to quit, /help)
+* alex connected
+10:24 alex: morning all
+10:25 sam: morning! which room are we using today?
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/help` | Show the command list |
+| `/rooms` | Rooms discovered on the LAN |
+| `/users` `/who` | Who is on the LAN and connected |
+| `/join <room>` | Join a room (created if nobody is in it) |
+| `/name <username>` | Change your display name |
+| `/connect <ip[:port]>` | Connect straight to a peer when discovery is blocked |
+| `/status` | Discovery state, ports, peers |
+| `/quit` | Exit |
+
+## How it works
+
+- Every instance sends a small UDP beacon (multicast + subnet broadcast)
+  announcing its username, room and TCP port.
+- Beacons are how instances find each other; then they open direct TCP
+  connections and exchange newline-delimited JSON messages.
+- Rooms are derived, not stored: a room exists while somebody is in it.
+- There is no server of any kind. If the LAN works, zapchat works.
+
+Works with the npm version of zapchat on the same network (same beacons, same
+message protocol).
+
+## Privacy
+
+- No accounts, no telemetry, no cloud: the only network traffic is UDP
+  beacons and TCP messages on your local network.
+- Config is one small JSON file (your username, a random client id, the last
+  room). Chat history stays in memory.
+- Messages are plain text on your LAN — anyone who can capture that traffic
+  can read it. For sensitive conversations use an encrypted messenger.
+
+## Requirements
+
+- Python 3.9+ (standard library only — zero dependencies)
+- Python 3.9+ on any OS: Windows, macOS, Linux
+
+## License
+
+MIT © Samarth Chugh (Sam3360)

zapchat-3.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+zapchat/__init__.py,sha256=I2wbd7t3aHjhkknzOYaDSRj1nTQ8LbRCV7suQ5zvf50,95
+zapchat/cli.py,sha256=S9uKuiyW3hAfkgvfndCMSKhOimeoBauot8EtKZCdDeU,12371
+zapchat/client.py,sha256=WREj3QFjdBOjib99M0yLIH4FHcmcvXEG7mgN6MrwCuM,11923
+zapchat/discovery.py,sha256=rpRfjzmpdNfgcwgj_YgR_XxHDSnch5ZeOOBxe5kHhhA,10746
+zapchat/protocol.py,sha256=TJR9DyR7RZHXGb_Xh2VHGbD7FCOwoCn64raYsFOLiPk,8017
+zapchat-3.0.0.dist-info/licenses/LICENSE,sha256=s9HH20McR0DRYxqylc7bo3MF0mBZqhQsM6V36RKAlFs,1080
+zapchat-3.0.0.dist-info/METADATA,sha256=1G9j5pI3HqmS0KcurAyac5W827kFN7W8jhMrFT5-DkU,3622
+zapchat-3.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+zapchat-3.0.0.dist-info/entry_points.txt,sha256=CA3RFPElbWY2YxgINBp3wx3RVJgPB840_fh4oidxQZY,45
+zapchat-3.0.0.dist-info/top_level.txt,sha256=u6fDbEZY2tCzrNGigqdG1kZopPxalnm2TSKYphvi3Rc,8
+zapchat-3.0.0.dist-info/RECORD,,

zapchat-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zapchat-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zapchat = zapchat.cli:main

zapchat-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samarth Chugh (Sam3360)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zapchat-3.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zapchat