py-ftpchat 0.2.0__tar.gz

py_ftpchat-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arbuztratil-design
+
+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.

py_ftpchat-0.2.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: py-ftpchat
+Version: 0.2.0
+Summary: A messenger where messages are literally files on an FTP server. Terminal client + browser gateway on one LAN host.
+Author: ftpchat contributors
+License-Expression: MIT
+Keywords: ftp,messenger,chat,networking,browser,lan
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: server
+Requires-Dist: pyftpdlib>=1.5; extra == "server"
+Dynamic: license-file
+
+# FTP Chat
+
+A messenger where messages are literally **files on an FTP server**. One
+device on the LAN hosts the chat; every other device joins from a **browser**
+(or the terminal client) — everything on the wire is FTP into that store.
+
+## How it works
+
+```
+        browser on phone/PC                 terminal client
+             │  HTTP/JSON                         │ ftplib
+             ▼                                   ▼
+      ftpchat-web (HTTP gateway)          ftpchat (terminal)
+             │  FTP (ftplib -> localhost)         │
+             ▼                                   ▼
+        ┌────────────────────────┐
+        │  pyftpdlib FTP server  │   storage = files:
+        │  rooms/general/*.txt   │   rooms/general/<ms>-<nick>.txt
+        │  users/<name>/*.txt    │
+        └────────────────────────┘
+```
+
+The host runs **one process** (`ftpchat-web`) that starts the FTP server and
+the browser gateway. The gateway itself speaks FTP to the local FTP server, so
+even the browser traffic becomes FTP file reads/writes.
+
+## Run (host PC)
+
+```
+pip install -e ".[server]"
+ftpchat-web
+```
+
+It prints the addresses to use, e.g.:
+
+```
+ftp (store):   127.0.0.1:2121
+browser:       http://192.168.0.5:8080
+terminal:      ftpchat --host <local-ip> --port 2121 --user name
+```
+
+* **Browser**: open `http://<host-ip>:8080` on any device in the network —
+  type a nickname and chat. No apps, no installs.
+* **Terminal client**: `ftpchat --host <host-ip> --user alice` (auto-registers
+  on first login). Commands: `/r <room>` `/to <user>` `/inbox` `/outbox`
+  `/users` `/rooms` `/refresh` `/quit`.
+
+Windows: double-click `ftpchat-web.bat` (from the launcher) to run the host.
+
+## Storage
+
+Messages are plain files named `<milliseconds>-<nick>.txt`:
+
+```
+from: phone
+at: 1789234637227
+room: general
+
+привет с браузера
+```
+
+Inspect the host folder (default `.ftpchat/rooms/general/`) to see every
+message as a file; edit/delete files there if you like.
+
+## Notes / security
+
+* Toy for a trusted LAN. New FTP users auto-register with any password, and the
+  authorizer hands everyone full access to the shared tree.
+* No TLS on FTP or HTTP. Do not expose to the internet.
+* Message text goes through FTP storage; the web page renders it with
+  `textContent` (no HTML injection).
+* Polling: browsers poll the gateway every 2 s, terminal polls the FTP store
+  every 2 s.
+
+## Tests
+
+```
+pip install -e ".[server]" pytest
+pytest            # 20 tests: protocol, FTP core, web gateway
+```

py_ftpchat-0.2.0/README.md

@@ -0,0 +1,80 @@
+# FTP Chat
+
+A messenger where messages are literally **files on an FTP server**. One
+device on the LAN hosts the chat; every other device joins from a **browser**
+(or the terminal client) — everything on the wire is FTP into that store.
+
+## How it works
+
+```
+        browser on phone/PC                 terminal client
+             │  HTTP/JSON                         │ ftplib
+             ▼                                   ▼
+      ftpchat-web (HTTP gateway)          ftpchat (terminal)
+             │  FTP (ftplib -> localhost)         │
+             ▼                                   ▼
+        ┌────────────────────────┐
+        │  pyftpdlib FTP server  │   storage = files:
+        │  rooms/general/*.txt   │   rooms/general/<ms>-<nick>.txt
+        │  users/<name>/*.txt    │
+        └────────────────────────┘
+```
+
+The host runs **one process** (`ftpchat-web`) that starts the FTP server and
+the browser gateway. The gateway itself speaks FTP to the local FTP server, so
+even the browser traffic becomes FTP file reads/writes.
+
+## Run (host PC)
+
+```
+pip install -e ".[server]"
+ftpchat-web
+```
+
+It prints the addresses to use, e.g.:
+
+```
+ftp (store):   127.0.0.1:2121
+browser:       http://192.168.0.5:8080
+terminal:      ftpchat --host <local-ip> --port 2121 --user name
+```
+
+* **Browser**: open `http://<host-ip>:8080` on any device in the network —
+  type a nickname and chat. No apps, no installs.
+* **Terminal client**: `ftpchat --host <host-ip> --user alice` (auto-registers
+  on first login). Commands: `/r <room>` `/to <user>` `/inbox` `/outbox`
+  `/users` `/rooms` `/refresh` `/quit`.
+
+Windows: double-click `ftpchat-web.bat` (from the launcher) to run the host.
+
+## Storage
+
+Messages are plain files named `<milliseconds>-<nick>.txt`:
+
+```
+from: phone
+at: 1789234637227
+room: general
+
+привет с браузера
+```
+
+Inspect the host folder (default `.ftpchat/rooms/general/`) to see every
+message as a file; edit/delete files there if you like.
+
+## Notes / security
+
+* Toy for a trusted LAN. New FTP users auto-register with any password, and the
+  authorizer hands everyone full access to the shared tree.
+* No TLS on FTP or HTTP. Do not expose to the internet.
+* Message text goes through FTP storage; the web page renders it with
+  `textContent` (no HTML injection).
+* Polling: browsers poll the gateway every 2 s, terminal polls the FTP store
+  every 2 s.
+
+## Tests
+
+```
+pip install -e ".[server]" pytest
+pytest            # 20 tests: protocol, FTP core, web gateway
+```

py_ftpchat-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-ftpchat"
+version = "0.2.0"
+description = "A messenger where messages are literally files on an FTP server. Terminal client + browser gateway on one LAN host."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ftpchat contributors" }]
+keywords = ["ftp", "messenger", "chat", "networking", "browser", "lan"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Chat",
+]
+
+[project.scripts]
+ftpchat-server = "ftpchat.server.cli:main"
+ftpchat = "ftpchat.client.terminal:main"
+ftpchat-web = "ftpchat.web.gateway:main"
+
+[project.optional-dependencies]
+server = ["pyftpdlib>=1.5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

py_ftpchat-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_ftpchat-0.2.0/src/ftpchat/__init__.py

@@ -0,0 +1 @@
+"""FTP chat: a messenger where messages are files on an FTP server."""

py_ftpchat-0.2.0/src/ftpchat/client/__init__.py

@@ -0,0 +1 @@
+"""FTP client core: the messenger logic over ftplib."""

py_ftpchat-0.2.0/src/ftpchat/client/core.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import ftplib
+import io
+import time
+
+from ..protocol import Message, encode, filename, parse, safe_part, seq_of_filename
+
+
+def _recursive_mkdir(ftp: ftplib.FTP, path: str) -> None:
+    parts = [p for p in path.split("/") if p]
+    current = ""
+    for part in parts:
+        current = f"{current}/{part}".lstrip("/")
+        try:
+            ftp.mkd(current)
+        except ftplib.error_perm:
+            pass
+
+
+def _read_text(ftp: ftplib.FTP, path: str) -> bytes:
+    buffer = io.BytesIO()
+    ftp.retrbinary(f"RETR {path}", buffer.write)
+    return buffer.getvalue()
+
+
+class FtpChat:
+    def __init__(
+        self,
+        host: str,
+        port: int = 2121,
+        user: str = "",
+        password: str = "",
+        timeout: float = 5.0,
+    ) -> None:
+        self.ftp = ftplib.FTP()
+        self.ftp.connect(host, port, timeout=timeout)
+        self.ftp.login(user, password)
+        self.user = safe_part(user)
+
+    def inbox_path(self, user: str | None = None) -> str:
+        return f"users/{safe_part(user or self.user)}/inbox"
+
+    def outbox_path(self, user: str | None = None) -> str:
+        return f"users/{safe_part(user or self.user)}/outbox"
+
+    def inbox_of(self, user: str) -> str:
+        return self.inbox_path(user)
+
+    def add_user(self, user: str) -> None:
+        for path in (self.inbox_of(user), f"users/{safe_part(user)}/outbox"):
+            _recursive_mkdir(self.ftp, path)
+
+    def send_dm(self, to: str, text: str) -> int:
+        to = safe_part(to)
+        self.add_user(to)
+        seq = int(time.time() * 1000)
+        payload = encode(self.user, text, recipient=to, at_ms=seq)
+        self.ftp.storbinary(f"STOR {self.inbox_of(to)}/{filename(seq, self.user)}", io.BytesIO(payload))
+        self.ftp.storbinary(f"STOR {self.outbox_path()}/{filename(seq, self.user)}", io.BytesIO(payload))
+        return seq
+
+    def send_room(self, room: str, text: str) -> int:
+        room = safe_part(room)
+        path = f"rooms/{room}"
+        _recursive_mkdir(self.ftp, path)
+        seq = int(time.time() * 1000)
+        payload = encode(self.user, text, room=room, at_ms=seq)
+        self.ftp.storbinary(f"STOR {path}/{filename(seq, self.user)}", io.BytesIO(payload))
+        self.ftp.storbinary(f"STOR {self.outbox_path()}/{filename(seq, self.user)}", io.BytesIO(payload))
+        return seq
+
+    def _list_messages(self, path: str) -> list[Message]:
+        try:
+            names = self.ftp.nlst(path)
+        except ftplib.error_perm:
+            return []
+        messages: list[Message] = []
+        for name in names:
+            seq = seq_of_filename(name)
+            if seq <= 0:
+                continue
+            try:
+                raw = _read_text(self.ftp, f"{path}/{name}")
+            except ftplib.error_perm:
+                continue
+            messages.append(parse(seq, raw))
+        messages.sort(key=lambda m: m.seq)
+        return messages
+
+    def list_inbox(self) -> list[Message]:
+        return self._list_messages(self.inbox_path())
+
+    def list_outbox(self) -> list[Message]:
+        return self._list_messages(self.outbox_path())
+
+    def list_room(self, room: str) -> list[Message]:
+        return self._list_messages(f"rooms/{safe_part(room)}")
+
+    def list_rooms(self) -> list[str]:
+        try:
+            names = self.ftp.nlst("rooms")
+        except ftplib.error_perm:
+            return []
+        return [n for n in names if n and not n.startswith(".")]
+
+    def list_users(self) -> list[str]:
+        try:
+            names = self.ftp.nlst("users")
+        except ftplib.error_perm:
+            return []
+        return [n for n in names if n and not n.startswith(".")]
+
+    def close(self) -> None:
+        try:
+            self.ftp.quit()
+        except (ftplib.error_perm, OSError):
+            try:
+                self.ftp.close()
+            except OSError:
+                pass

py_ftpchat-0.2.0/src/ftpchat/client/terminal.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import threading
+import time
+
+from ..protocol import Message
+from .core import FtpChat
+
+
+class Pr(threading.Thread):
+    def __init__(self, chat: FtpChat) -> None:
+        super().__init__(daemon=True)
+        self.chat = chat
+        self._print_lock = threading.Lock()
+        self._max: int = 0
+        self._scope = "room:general"
+        self._stop = threading.Event()
+
+    def out(self, line: str) -> None:
+        with self._print_lock:
+            print(line, flush=True)
+
+    @staticmethod
+    def _hm(seq: int) -> str:
+        return time.strftime("%H:%M:%S", time.localtime(seq / 1000)) if seq else "--:--:--"
+
+    @staticmethod
+    def _fmt(msg: Message) -> str:
+        if msg.room:
+            return f"[{Pr._hm(msg.seq)}] room#{msg.room} <{msg.sender}> {msg.text}"
+        return f"[{Pr._hm(msg.seq)}] {msg.sender}: {msg.text}"
+
+    def set_scope(self, scope: str) -> None:
+        self._max = 0
+        self._scope = scope
+
+    def _fetch(self) -> list[Message]:
+        scope = self._scope
+        if scope.startswith("room:"):
+            return self.chat.list_room(scope.split(":", 1)[1])
+        if scope.startswith("dm:"):
+            return self.chat.list_inbox()
+        return []
+
+    def snapshot(self) -> None:
+        msgs = self._fetch()
+        for m in msgs:
+            self.out(Pr._fmt(m))
+        self._max = max((m.seq for m in msgs), default=self._max)
+
+    def poll_once(self) -> None:
+        try:
+            msgs = self._fetch()
+        except Exception as exc:  # noqa: BLE001
+            self.out(f"! poll failed: {exc}")
+            return
+        new_max = self._max
+        for m in msgs:
+            if m.seq > new_max:
+                self.out(Pr._fmt(m) + "  <new>")
+                new_max = m.seq
+        self._max = new_max
+
+    def run(self) -> None:
+        while not self._stop.wait(2.0):
+            self.poll_once()
+
+
+class TerminalApp:
+    def __init__(self, args) -> None:
+        self.args = args
+        self.chat = FtpChat(args.host, args.port, args.user, args.password)
+        self.room = "general"
+        self.dm_to: str | None = None
+        self.pr = Pr(self.chat)
+
+    @property
+    def scope(self) -> str:
+        return f"room:{self.room}" if self.room else f"dm:{self.dm_to}"
+
+    def run(self) -> None:
+        self.pr.start()
+        self.pr.snapshot()
+        self.pr.out(f"connected as {self.chat.user}; scope: {self.scope}")
+        self.pr.out("/r <room> | /to <user> | /inbox | /outbox | /users | /rooms | /refresh | /quit")
+        try:
+            while True:
+                line = input("> ").strip()
+                if not line:
+                    continue
+                if line.startswith("/"):
+                    if not self._cmd(line):
+                        break
+                else:
+                    self._send(line)
+        except (KeyboardInterrupt, EOFError):
+            self.pr.out("bye")
+        finally:
+            self.pr._stop.set()
+            self.chat.close()
+
+    def _send(self, text: str) -> None:
+        try:
+            if self.room:
+                self.chat.send_room(self.room, text)
+            elif self.dm_to:
+                self.chat.send_dm(self.dm_to, text)
+                self.pr.out(f"[{Pr._hm(int(time.time() * 1000))}] -> {self.dm_to}: {text}")
+            else:
+                self.pr.out("! pick scope: /r <room> or /to <user>")
+        except Exception as exc:  # noqa: BLE001
+            self.pr.out(f"! send failed: {exc}")
+
+    def _cmd(self, line: str) -> bool:
+        parts = line.split()
+        cmd, rest = parts[0], " ".join(parts[1:])
+        try:
+            if cmd in ("/q", "/quit", "/exit"):
+                self.pr.out("bye")
+                return False
+            if cmd in ("/r", "/room"):
+                self.room = rest or self.room
+                self.dm_to = None
+                self.pr.set_scope(self.scope)
+                self.pr.snapshot()
+                self.pr.out(f"now on room '{self.room}'")
+            elif cmd == "/to":
+                self.dm_to = rest or None
+                if self.dm_to:
+                    self.chat.add_user(self.dm_to)
+                self.room = ""
+                self.pr.set_scope(self.scope)
+                self.pr.snapshot()
+                self.pr.out(f"dm with {self.dm_to}" if self.dm_to else "dm off")
+            elif cmd == "/inbox":
+                msgs = self.chat.list_inbox()
+                if not msgs:
+                    self.pr.out("inbox empty")
+                for m in msgs:
+                    self.pr.out(Pr._fmt(m))
+            elif cmd == "/outbox":
+                msgs = self.chat.list_outbox()
+                if not msgs:
+                    self.pr.out("outbox empty")
+                for m in msgs:
+                    r = m.recipient or m.room
+                    self.pr.out(f"[{Pr._hm(m.seq)}] -> {r}: {m.text}")
+            elif cmd == "/users":
+                users = self.chat.list_users()
+                self.pr.out("users: " + (", ".join(users) if users else "none yet"))
+            elif cmd == "/rooms":
+                rooms = self.chat.list_rooms()
+                self.pr.out("rooms: " + (", ".join(rooms) if rooms else "none yet"))
+            elif cmd == "/refresh":
+                self.pr.snapshot()
+            elif cmd == "/help":
+                self.pr.out("/r <room> | /to <user> | /inbox | /outbox | /users | /rooms | /refresh | /quit")
+            else:
+                self.pr.out(f"! unknown: {cmd}")
+        except Exception as exc:  # noqa: BLE001
+            self.pr.out(f"! {exc}")
+        return True
+
+
+def _use_utf8() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (OSError, ValueError):
+                pass
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ftpchat", description="FTP messenger: terminal client.")
+    parser.add_argument("--host", default="127.0.0.1", help="FTP server host")
+    parser.add_argument("--port", type=int, default=2121, help="FTP server port")
+    parser.add_argument("--user", required=True, help="your username")
+    parser.add_argument("--password", default="", help="your password")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    _use_utf8()
+    args = _build_parser().parse_args(argv)
+    try:
+        TerminalApp(args).run()
+    except Exception as exc:  # noqa: BLE001
+        print(f"! cannot connect: {exc}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

py_ftpchat-0.2.0/src/ftpchat/protocol.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Message:
+    seq: int
+    sender: str
+    recipient: str | None
+    room: str | None
+    at_ms: int
+    text: str
+
+
+def encode(
+    sender: str,
+    text: str,
+    recipient: str | None = None,
+    room: str | None = None,
+    at_ms: int | None = None,
+) -> bytes:
+    at_ms = int(at_ms) if at_ms is not None else int(time.time() * 1000)
+    lines = [f"from: {sender}", f"at: {at_ms}"]
+    if recipient:
+        lines.append(f"to: {recipient}")
+    if room:
+        lines.append(f"room: {room}")
+    return ("\n".join(lines) + "\n\n" + text).encode("utf-8")
+
+
+def parse(seq: int, raw: bytes) -> Message:
+    text_part = raw.decode("utf-8", "replace")
+    heads, _, body = text_part.partition("\n\n")
+    headers: dict[str, str] = {}
+    for line in heads.splitlines():
+        if ":" in line:
+            key, _, value = line.partition(":")
+            headers[key.strip()] = value.strip()
+    return Message(
+        seq=seq,
+        sender=headers.get("from", "?"),
+        recipient=headers.get("to"),
+        room=headers.get("room"),
+        at_ms=int(headers.get("at") or 0),
+        text=body.strip("\ufeff\n"),
+    )
+
+
+def filename(at_ms: int, sender: str) -> str:
+    return f"{at_ms}-{sender}.txt"
+
+
+def seq_of_filename(name: str) -> int:
+    try:
+        return int(name.split("-", 1)[0])
+    except ValueError:
+        return 0
+
+
+def safe_part(name: str, max_len: int = 32) -> str:
+    cleaned = "".join(ch for ch in name if ch.isalnum() or ch in "_-")
+    return cleaned[:max_len].strip("-_") or "guest"

py_ftpchat-0.2.0/src/ftpchat/server/__init__.py

@@ -0,0 +1 @@
+"""FTP server side of ftpchat."""