flux-sockets 0.6.4__py3-none-any.whl

flux/__init__.py

@@ -0,0 +1,5 @@
+from .server import Server, ServerClient, Room
+from .client import Client
+
+__all__ = ["Server", "ServerClient", "Room", "Client"]
+__version__ = "0.1.0"

flux/client.py

@@ -0,0 +1,115 @@
+import socket
+import threading
+
+from .events import Events
+from .protocol import ConnectionClosed, Reader, TCPTransport, decode, encode
+
+
+class Client(Events):
+    """Python client. Emits made before the connection is up are queued and sent on connect."""
+
+    def __init__(self, host="localhost", port=5000, token=None, reconnect=True,
+                 reconnect_delay=1.0, max_delay=15.0, connect_timeout=10.0):
+        super().__init__()
+        self.host, self.port, self.token = host, port, token
+        self.reconnect = reconnect
+        self.reconnect_delay, self.max_delay = reconnect_delay, max_delay
+        self.connect_timeout = connect_timeout
+        self.id = None
+        self.connected = False
+        self._transport = None
+        self._pending = []
+        self._lock = threading.RLock()
+        self._stop = threading.Event()
+        self._ready = threading.Event()
+        self._thread = None
+
+    # public API 
+    def emit(self, event, data=None):
+        text = encode(event, data)
+        with self._lock:
+            if self.connected and self._transport:
+                try:
+                    self._transport.send(text)
+                    return True
+                except OSError:
+                    pass
+            if len(self._pending) < 1000:
+                self._pending.append(text)
+        return False
+
+    def run(self):
+        """Block, connecting (and reconnecting) until close() is called."""
+        self._stop.clear()
+        delay = self.reconnect_delay
+        while not self._stop.is_set():
+            try:
+                sock = socket.create_connection((self.host, self.port), self.connect_timeout)
+            except OSError as e:
+                if not self.reconnect:
+                    raise ConnectionError(f"could not connect to {self.host}:{self.port}") from e
+                if self._stop.wait(delay):
+                    break
+                delay = min(delay * 2, self.max_delay)
+                continue
+            delay = self.reconnect_delay
+            sock.settimeout(None)
+            sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            transport = TCPTransport(sock, Reader(sock))
+            self._transport = transport
+            try:
+                transport.send(encode("__hello"))
+                if self.token is not None:
+                    transport.send(encode("auth", self.token))
+                while True:
+                    event, data = decode(transport.recv())
+                    self._handle(event, data)
+            except (ConnectionClosed, OSError):
+                pass
+            finally:
+                with self._lock:
+                    was, self.connected = self.connected, False
+                    self._transport = None
+                self._ready.clear()
+                transport.close()
+                if was:
+                    self._fire("disconnect")
+            if not self.reconnect or self._stop.wait(delay):
+                break
+
+    def start(self):
+        """Run in a background thread."""
+        self._thread = threading.Thread(target=self.run, daemon=True)
+        self._thread.start()
+        return self
+
+    def wait_connected(self, timeout=None):
+        return self._ready.wait(timeout)
+
+    def close(self):
+        self._stop.set()
+        t = self._transport
+        if t:
+            t.close()
+
+    # internals 
+    def _handle(self, event, data):
+        if event == "__ping":
+            try:
+                self._transport.send(encode("__pong"))
+            except OSError:
+                pass
+            return
+        if event == "welcome":
+            self.id = data.get("id") if isinstance(data, dict) else None
+            with self._lock:
+                while self._pending:
+                    self._transport.send(self._pending[0])
+                    self._pending.pop(0)
+                self.connected = True
+            self._ready.set()
+            self._fire("connect")
+        elif event == "auth_failed":
+            self._stop.set()
+        self._fire("*", event, data)
+        self._fire(event, data)

flux/events.py

@@ -0,0 +1,36 @@
+import inspect
+import traceback
+
+
+def arity(fn):
+    """How many positional args a handler accepts, so handlers can take fewer args."""
+    try:
+        params = inspect.signature(fn).parameters.values()
+    except (TypeError, ValueError):
+        return 99
+    n = 0
+    for p in params:
+        if p.kind == p.VAR_POSITIONAL:
+            return 99
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD):
+            n += 1
+    return n
+
+
+class Events:
+    def __init__(self):
+        self._handlers = {}
+
+    def on(self, event, fn=None):
+        """Use as @obj.on("event") or obj.on("event", fn)."""
+        def register(f):
+            self._handlers.setdefault(event, []).append((f, arity(f)))
+            return f
+        return register(fn) if fn else register
+
+    def _fire(self, event, *args):
+        for fn, n in list(self._handlers.get(event, ())):
+            try:
+                fn(*args[:n])
+            except Exception:
+                traceback.print_exc()

flux/protocol.py

@@ -0,0 +1,187 @@
+import base64
+import hashlib
+import json
+import socket
+import struct
+import threading
+import time
+
+GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+MAX_MESSAGE = 1 << 20  # 1 MiB
+
+
+class ConnectionClosed(Exception):
+    pass
+
+
+def encode(event, data=None):
+    return json.dumps(
+        {"event": event, "data": data}, separators=(",", ":"), default=str
+    )
+
+
+def decode(text):
+    try:
+        obj = json.loads(text)
+    except ValueError:
+        return "message", text
+    if isinstance(obj, dict) and isinstance(obj.get("event"), str):
+        return obj["event"], obj.get("data")
+    return "message", obj
+
+
+class Reader:
+    def __init__(self, sock):
+        self.sock = sock
+        self.buf = bytearray()
+        self.last_activity = time.monotonic()
+
+    def _fill(self):
+        try:
+            chunk = self.sock.recv(65536)
+        except OSError as e:
+            raise ConnectionClosed(str(e))
+        if not chunk:
+            raise ConnectionClosed()
+        self.last_activity = time.monotonic()
+        self.buf += chunk
+
+    def read_exact(self, n):
+        while len(self.buf) < n:
+            self._fill()
+        out = bytes(self.buf[:n])
+        del self.buf[:n]
+        return out
+
+    def read_until(self, delim, limit=MAX_MESSAGE):
+        while True:
+            i = self.buf.find(delim)
+            if i != -1:
+                out = bytes(self.buf[:i])
+                del self.buf[: i + len(delim)]
+                return out
+            if len(self.buf) > limit:
+                raise ConnectionClosed("message too large")
+            self._fill()
+
+
+class _Transport:
+    def __init__(self, sock, reader):
+        self.sock = sock
+        self.reader = reader
+        self._wlock = threading.Lock()
+
+    def _write(self, data):
+        with self._wlock:
+            self.sock.sendall(data)
+
+    def close(self):
+        for fn in (lambda: self.sock.shutdown(socket.SHUT_RDWR), self.sock.close):
+            try:
+                fn()
+            except OSError:
+                pass
+
+
+class TCPTransport(_Transport):
+    kind = "tcp"
+
+    def recv(self):
+        while True:
+            line = self.reader.read_until(b"\n").strip()
+            if line:
+                return line.decode("utf-8", "replace")
+
+    def send(self, text):
+        self._write(text.encode() + b"\n")
+
+    def ping(self):
+        self.send(encode("__ping"))
+
+
+def _unmask(data, mask):
+    if not data:
+        return data
+    m = (mask * (len(data) // 4 + 1))[: len(data)]
+    return (int.from_bytes(data, "big") ^ int.from_bytes(m, "big")).to_bytes(
+        len(data), "big"
+    )
+
+
+class WSTransport(_Transport):
+    kind = "websocket"
+
+    @staticmethod
+    def _frame(opcode, payload=b""):
+        n = len(payload)
+        head = bytes([0x80 | opcode])
+        if n < 126:
+            head += bytes([n])
+        elif n < 65536:
+            head += b"\x7e" + struct.pack(">H", n)
+        else:
+            head += b"\x7f" + struct.pack(">Q", n)
+        return head + payload
+
+    def send(self, text):
+        self._write(self._frame(1, text.encode()))
+
+    def ping(self):
+        self._write(self._frame(9))
+
+    def recv(self):
+        r = self.reader
+        message = bytearray()
+        while True:
+            b1, b2 = r.read_exact(2)
+            fin, op = b1 & 0x80, b1 & 0x0F
+            n = b2 & 0x7F
+            if n == 126:
+                n = struct.unpack(">H", r.read_exact(2))[0]
+            elif n == 127:
+                n = struct.unpack(">Q", r.read_exact(8))[0]
+            if n > MAX_MESSAGE:
+                raise ConnectionClosed("frame too large")
+            mask = r.read_exact(4) if b2 & 0x80 else None
+            payload = r.read_exact(n)
+            if mask:
+                payload = _unmask(payload, mask)
+            if op == 8:
+                try:
+                    self._write(self._frame(8, payload[:2]))
+                except OSError:
+                    pass
+                raise ConnectionClosed()
+            if op == 9:
+                self._write(self._frame(10, payload))
+                continue
+            if op == 10:
+                continue
+            message += payload
+            if len(message) > MAX_MESSAGE:
+                raise ConnectionClosed("message too large")
+            if fin:
+                return message.decode("utf-8", "replace")
+
+
+def ws_server_handshake(sock, reader):
+    head = reader.read_until(b"\r\n\r\n", 16384).decode("latin-1")
+    headers = {}
+    for line in head.split("\r\n")[1:]:
+        if ":" in line:
+            k, v = line.split(":", 1)
+            headers[k.strip().lower()] = v.strip()
+    key = headers.get("sec-websocket-key")
+    if not key:
+        sock.sendall(
+            b"HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\nWebSocket only."
+        )
+        raise ConnectionClosed("not a websocket request")
+    accept = base64.b64encode(hashlib.sha1((key + GUID).encode()).digest()).decode()
+    sock.sendall(
+        (
+            "HTTP/1.1 101 Switching Protocols\r\n"
+            "Upgrade: websocket\r\nConnection: Upgrade\r\n"
+            f"Sec-WebSocket-Accept: {accept}\r\n\r\n"
+        ).encode()
+    )

flux/server.py

@@ -0,0 +1,287 @@
+import socket
+import threading
+import time
+import traceback
+import uuid
+
+from .events import Events, arity
+from .protocol import (ConnectionClosed, Reader, TCPTransport, WSTransport,
+                       decode, encode, ws_server_handshake)
+
+_MISSING = object()
+
+
+class ServerClient:
+    """One connected peer (TCP or WebSocket) as seen by the server."""
+
+    def __init__(self, server, transport, address):
+        self.server = server
+        self.transport = transport
+        self.address = address
+        self.id = uuid.uuid4().hex[:8]
+        self.name = "client-" + self.id
+        self.data = {}
+        self.rooms = set()
+        self.connected = True
+        self.authenticated = False
+        self.connected_at = time.monotonic()
+
+    @property
+    def kind(self):
+        return self.transport.kind
+
+    @property
+    def last_seen(self):
+        return self.transport.reader.last_activity
+
+    def send(self, event, data=_MISSING):
+        """client.send(data) -> "message" event, or client.send("event", data)."""
+        if data is _MISSING:
+            event, data = "message", event
+        return self._send_text(encode(event, data))
+
+    def emit(self, event, data=None):
+        return self._send_text(encode(event, data))
+
+    def _send_text(self, text):
+        if not self.connected:
+            return False
+        try:
+            self.transport.send(text)
+            return True
+        except OSError:
+            self.close()
+            return False
+
+    def join(self, room):
+        return self.server.room(room).join(self)
+
+    def leave(self, room):
+        r = self.server._rooms.get(room)
+        if r:
+            r.leave(self)
+
+    def close(self):
+        self.connected = False
+        self.transport.close()
+
+    def __repr__(self):
+        return f"<Client {self.id} {self.kind} {self.address[0]}>"
+
+
+class Room:
+    def __init__(self, server, name):
+        self.server = server
+        self.name = name
+        self._members = {}
+
+    @property
+    def clients(self):
+        with self.server._lock:
+            return list(self._members.values())
+
+    def join(self, client):
+        with self.server._lock:
+            self._members[client.id] = client
+            client.rooms.add(self.name)
+            self.server._rooms[self.name] = self
+        return self
+
+    def leave(self, client):
+        with self.server._lock:
+            self._members.pop(client.id, None)
+            client.rooms.discard(self.name)
+            if not self._members and self.server._rooms.get(self.name) is self:
+                del self.server._rooms[self.name]
+
+    def emit(self, event, data=None, exclude=None):
+        text = encode(event, data)
+        for c in self.clients:
+            if exclude is None or c is not exclude:
+                c._send_text(text)
+
+    def __len__(self):
+        return len(self._members)
+
+    def __contains__(self, client):
+        return client.id in self._members
+
+    def __repr__(self):
+        return f"<Room {self.name!r} ({len(self)})>"
+
+
+class Server(Events):
+    def __init__(self, port=5000, host="0.0.0.0", heartbeat=15, timeout=45,
+                 sniff_timeout=0.5, auth_timeout=10, quiet=False):
+        super().__init__()
+        self.host, self.port = host, port
+        self.heartbeat, self.timeout = heartbeat, timeout
+        self.sniff_timeout, self.auth_timeout = sniff_timeout, auth_timeout
+        self.quiet = quiet
+        self.clients = {}
+        self._rooms = {}
+        self._lock = threading.RLock()
+        self._stop = threading.Event()
+        self._listener = None
+        self._auth = None
+
+    # public API
+    def auth(self, fn):
+        """@server.auth  def check(client, token): return True/False"""
+        self._auth = (fn, arity(fn))
+        return fn
+
+    def room(self, name):
+        with self._lock:
+            return self._rooms.get(name) or Room(self, name)
+
+    def broadcast(self, event, data=None, exclude=None):
+        text = encode(event, data)
+        with self._lock:
+            targets = list(self.clients.values())
+        for c in targets:
+            if c.authenticated and (exclude is None or c is not exclude):
+                c._send_text(text)
+
+    def run(self):
+        """Block and serve until Ctrl+C."""
+        self._bind()
+        self._log(f"flux listening on {self.host}:{self.port} (tcp + websocket)")
+        threading.Thread(target=self._monitor, daemon=True).start()
+        try:
+            self._accept_loop()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.stop()
+
+    def start(self):
+        """Serve in a background thread and return immediately."""
+        self._bind()
+        threading.Thread(target=self._monitor, daemon=True).start()
+        threading.Thread(target=self._accept_loop, daemon=True).start()
+        return self
+
+    def stop(self):
+        self._stop.set()
+        if self._listener:
+            try:
+                self._listener.close()
+            except OSError:
+                pass
+        for c in list(self.clients.values()):
+            c.close()
+
+    # internals
+    def _log(self, *a):
+        if not self.quiet:
+            print(*a)
+
+    def _bind(self):
+        s = socket.socket()
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((self.host, self.port))
+        s.listen(128)
+        s.settimeout(0.5)
+        self.port = s.getsockname()[1]
+        self._listener = s
+        self._stop.clear()
+
+    def _accept_loop(self):
+        while not self._stop.is_set():
+            try:
+                sock, addr = self._listener.accept()
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            threading.Thread(target=self._serve, args=(sock, addr), daemon=True).start()
+
+    def _monitor(self):
+        while not self._stop.wait(self.heartbeat):
+            now = time.monotonic()
+            for c in list(self.clients.values()):
+                if now - c.last_seen > self.timeout:
+                    c.close()
+                elif not c.authenticated and now - c.connected_at > self.auth_timeout:
+                    c.close()
+                else:
+                    try:
+                        c.transport.ping()
+                    except OSError:
+                        c.close()
+
+    def _negotiate(self, sock):
+        reader = Reader(sock)
+        sock.settimeout(self.sniff_timeout)
+        try:
+            first = sock.recv(4, socket.MSG_PEEK)
+            if not first:
+                raise ConnectionClosed()
+        except socket.timeout:
+            first = b""
+        except OSError:
+            raise ConnectionClosed()
+        sock.settimeout(10)
+        if first[:3] == b"GET":
+            ws_server_handshake(sock, reader)
+            sock.settimeout(None)
+            return WSTransport(sock, reader)
+        sock.settimeout(None)
+        return TCPTransport(sock, reader)
+
+    def _admit(self, client):
+        client.authenticated = True
+        client.emit("welcome", {"id": client.id})
+        self._fire("connect", client)
+        return True
+
+    def _serve(self, sock, address):
+        try:
+            transport = self._negotiate(sock)
+        except (ConnectionClosed, OSError):
+            sock.close()
+            return
+        client = ServerClient(self, transport, address)
+        with self._lock:
+            self.clients[client.id] = client
+        announced = False
+        try:
+            if self._auth is None:
+                announced = self._admit(client)
+            else:
+                client.emit("auth_required")
+            while True:
+                event, data = decode(transport.recv())
+                if event in ("__pong", "__hello"):
+                    continue
+                if not client.authenticated:
+                    if event != "auth":
+                        continue
+                    fn, n = self._auth
+                    ok = False
+                    try:
+                        ok = bool(fn(*(client, data)[:n]))
+                    except Exception:
+                        traceback.print_exc()
+                    if not ok:
+                        client.emit("auth_failed")
+                        break
+                    announced = self._admit(client)
+                    continue
+                self._fire("*", client, event, data)
+                self._fire(event, client, data)
+        except ConnectionClosed:
+            pass
+        except Exception:
+            traceback.print_exc()
+        finally:
+            client.connected = False
+            for r in list(client.rooms):
+                client.leave(r)
+            with self._lock:
+                self.clients.pop(client.id, None)
+            transport.close()
+            if announced:
+                self._fire("disconnect", client)

flux_sockets-0.6.4.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: flux-sockets
+Version: 0.6.4
+Summary: Dead-simple sockets: events, rooms, JSON and WebSockets in a few lines.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TheOrangeCow/flux
+Project-URL: Repository, https://github.com/TheOrangeCow/flux
+Project-URL: Issues, https://github.com/TheOrangeCow/flux/issues
+Keywords: sockets,networking,websockets,events,multiplayer,realtime
+Requires-Python: >=3.8
+License-File: LICENSE
+Dynamic: license-file

flux_sockets-0.6.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+flux/__init__.py,sha256=slUgf5Krb7wzVIXpx0OWDXj0FkrsMqOwtGFMzlM8vWM,152
+flux/client.py,sha256=xGnhk2-YW60lG-WUg86umBj3Ns_IsD0Ag9xey2wwkss,4088
+flux/events.py,sha256=KCWVXLshzwsKfwWQ0vsH4i2z2qgnJTHjsbr0aoKZf_Y,988
+flux/protocol.py,sha256=7UGXY-YX3eSJA3J8myj-a31ddhEEWmaCcR6G5L6njhw,5131
+flux/server.py,sha256=BMkBDO6DP77Pz5jALIZemUVvyCDkoN0ujam9VkNYLCY,8895
+flux_sockets-0.6.4.dist-info/licenses/LICENSE,sha256=v6-ByutdA9HMF3T0mHfLOHSqi5TsddF6tahFwjNIiLo,1090
+flux_sockets-0.6.4.dist-info/METADATA,sha256=5kVzbaGRa0vnlF6tsjfLaIbsPPhfxL6Bo8fFopCnT9Q,495
+flux_sockets-0.6.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flux_sockets-0.6.4.dist-info/top_level.txt,sha256=9txNc7btJudkur68qMJ7nT64gBMfFJm2dFvfYLaFBc4,5
+flux_sockets-0.6.4.dist-info/RECORD,,

flux_sockets-0.6.4.dist-info/WHEEL

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

flux_sockets-0.6.4.dist-info/licenses/LICENSE

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

flux_sockets-0.6.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+flux