zynko 0.1.0__py3-none-any.whl

zynko/client.py

@@ -0,0 +1,471 @@
+"""A Zynko bot: the gateway, the caches and the events."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+from ._events import Emitter
+from .bits import Intents, Permissions
+from .gateway import Gateway, GatewayClosed
+from .interaction import Interaction
+from .message import Message
+from .models import Card, Channel, Components, Emoji, Guild, Member, Role, User, VoiceState
+from .permissions import compute_permissions
+from .rest import FileInput, Rest
+
+if TYPE_CHECKING:
+    from .voice import VoiceConnection
+
+__all__ = ["Client"]
+
+log = logging.getLogger("zynko")
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+#: The events a client emits, and what each handler gets.
+EVENTS = {
+    "ready": "user: User - connected (again): the caches were rebuilt from READY",
+    "message_create": "message: Message",
+    "message_update": "message: Message",
+    "message_delete": "data: {id, channel_id}",
+    "reaction_add": "data: {message_id, channel_id, user_id, emoji}",
+    "reaction_remove": "data: {message_id, channel_id, user_id, emoji}",
+    "typing_start": "data: {channel_id, user_id, timestamp}",
+    "guild_create": "guild: Guild - added to a guild, or each guild in READY",
+    "guild_update": "guild: Guild",
+    "guild_delete": "guild_id: str",
+    "channel_create": "channel: Channel",
+    "channel_update": "channel: Channel, previous: Channel | None",
+    "channel_delete": "channel: Channel",
+    "member_add": "member: Member",
+    "member_update": "member: Member, previous: Member | None",
+    "member_remove": "data: {guild_id, user_id}",
+    "presence_update": "data: {user_id, status}",
+    "voice_state_update": "state: VoiceState, previous: VoiceState | None",
+    "interaction": "interaction: Interaction",
+    "raw": "type: str, data: Any - every gateway event, as it came",
+    "reconnecting": "info: {code, reason, wait} - the link dropped; connecting again",
+    "error": "error: Exception - a handler failed, or the token was refused",
+}
+
+
+class Client:
+    """A Zynko bot: connects to the gateway, keeps guilds, channels and members up to date,
+    and turns events into handler calls::
+
+        client = zynko.Client(intents=Intents.GUILDS | Intents.MESSAGES)
+
+        @client.on("message_create")
+        async def ping(msg: zynko.Message):
+            if msg.content == "!ping":
+                await msg.reply("pong")
+
+        client.run(os.environ["ZYNKO_TOKEN"])
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        intents: int = Intents.GUILDS | Intents.MESSAGES,
+        api: str | None = None,
+        gateway: str | None = None,
+    ) -> None:
+        self.rest = Rest(token or "", api=api)
+        self.intents = Intents(intents)
+        self._gateway_url = gateway
+        #: The bot's account, once connected.
+        self.user: User | None = None
+        self.session_id = ""
+        #: Guilds (servidores) by id.
+        self.guilds: dict[str, Guild] = {}
+        #: Every channel the bot sees, DMs included.
+        self.channels: dict[str, Channel] = {}
+        self.users: dict[str, User] = {}
+        #: Who is in voice, by user id (needs VOICE_STATES).
+        self.voice_states: dict[str, VoiceState] = {}
+        #: The voice room the bot is in: one at a time, as for anyone.
+        self.voice: VoiceConnection | None = None
+        self._events = Emitter("zynko")
+        self._gateway: Gateway | None = None
+        self._first_ready: asyncio.Future[User] | None = None
+        self._closed: asyncio.Event | None = None
+
+    # ---------- events ----------
+
+    @overload
+    def on(self, event: str) -> Callable[[F], F]: ...
+    @overload
+    def on(self, event: str, handler: F) -> F: ...
+    def on(self, event: str, handler: F | None = None) -> Any:
+        """Registers a handler, as a call or a decorator: ``@client.on("message_create")``."""
+        return self._events.on(event, handler) if handler is not None else self._events.on(event)
+
+    def once(self, event: str, handler: F) -> F:
+        return self._events.once(event, handler)
+
+    def off(self, event: str, handler: Callable[..., Any]) -> None:
+        self._events.off(event, handler)
+
+    def event(self, handler: F) -> F:
+        """Registers ``on_<event>`` by its name: ``@client.event async def on_message_create(msg)``."""
+        name = handler.__name__
+        if not name.startswith("on_"):
+            raise ValueError(f"O nome do handler precisa começar com on_ (veio {name!r})")
+        self._events.on(name[3:], handler)
+        return handler
+
+    async def wait_for(self, event: str, check: Callable[..., bool] | None = None, timeout: float | None = 30.0) -> Any:
+        """Waits for the next ``event`` that passes ``check``; its argument (or a tuple of them).
+
+        Raises ``asyncio.TimeoutError`` after ``timeout`` seconds.
+        """
+        return await self._events.wait_for(event, check, timeout)
+
+    def _emit(self, event: str, *args: Any) -> None:
+        self._events.emit(event, *args)
+
+    # ---------- connection ----------
+
+    @property
+    def token(self) -> str:
+        return self.rest.token
+
+    async def login(self, token: str | None = None) -> User:
+        """Connects; returns the bot's account once READY arrives. The link stays up in the
+        background, reconnecting by itself, until :meth:`close`."""
+        if token:
+            self.rest.token = token
+        if not self.rest.token:
+            raise ValueError("Falta o token do bot (crie um em dev.zynko.org)")
+        loop = asyncio.get_running_loop()
+        self._closed = asyncio.Event()
+        self._first_ready = loop.create_future()
+        url = self._gateway_url or re.sub(r"^http", "ws", self.rest.api) + "/gateway"
+        self._gateway = Gateway(
+            url=url,
+            token=self.rest.token,
+            intents=self.intents,
+            session=lambda: self.rest.session,
+            on_dispatch=self._dispatch,
+            on_state=self._on_state,
+        )
+        task = self._gateway.start()
+        waiter = self._first_ready
+        pending: set[asyncio.Future[Any]] = {waiter, task}
+        done, _ = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
+        if waiter in done:
+            return waiter.result()
+        task.result()
+        raise RuntimeError("O gateway parou antes do READY")
+
+    async def start(self, token: str | None = None) -> None:
+        """Connects and runs until :meth:`close` (or a refused token)."""
+        await self.login(token)
+        assert self._closed is not None
+        await self._closed.wait()
+
+    def run(self, token: str | None = None) -> None:
+        """Connects and blocks until Ctrl+C or :meth:`close`. The simplest way to run a bot."""
+
+        async def main() -> None:
+            try:
+                await self.start(token)
+            finally:
+                await self.close()
+
+        try:
+            asyncio.run(main())
+        except KeyboardInterrupt:
+            pass
+
+    async def close(self) -> None:
+        """Leaves voice and closes the link."""
+        if self.voice is not None:
+            try:
+                await self.voice.leave()
+            except Exception:  # noqa: BLE001
+                log.debug("leaving voice failed", exc_info=True)
+        if self._gateway is not None:
+            await self._gateway.close()
+        await self.rest.close()
+        if self._closed is not None:
+            self._closed.set()
+
+    #: Same as :meth:`close`, by the JavaScript library's name.
+    destroy = close
+
+    @property
+    def closed(self) -> bool:
+        return self._closed is not None and self._closed.is_set()
+
+    async def send_op(self, op: int, d: Any) -> bool:
+        """Sends a gateway op. Used by the voice connection (op 4)."""
+        return await self._gateway.send(op, d) if self._gateway else False
+
+    def _on_state(self, state: str, detail: Any) -> None:
+        if state == "reconnecting" and detail:
+            self._emit("reconnecting", detail)
+        elif state == "closed":
+            err = detail if isinstance(detail, Exception) else GatewayClosed("Gateway fechado")
+            if self._first_ready is not None and not self._first_ready.done():
+                self._first_ready.set_exception(err)
+            else:
+                self._emit("error", err)
+            if self._closed is not None:
+                self._closed.set()
+
+    # ---------- shortcuts ----------
+
+    async def send(
+        self,
+        channel_id: str,
+        content: str | None = None,
+        *,
+        reply_to: str | None = None,
+        files: list[FileInput] | None = None,
+        nonce: str | None = None,
+        cards: list[Card] | None = None,
+        components: Components | None = None,
+    ) -> Message:
+        """Sends a message to a channel; files are uploaded first."""
+        data = await self.rest.send(
+            channel_id, content, reply_to=reply_to, files=files, nonce=nonce, cards=cards, components=components
+        )
+        return Message(self, data)
+
+    async def send_dm(
+        self,
+        user_id: str,
+        content: str | None = None,
+        *,
+        files: list[FileInput] | None = None,
+        cards: list[Card] | None = None,
+        components: Components | None = None,
+    ) -> Message:
+        """Sends someone a direct message."""
+        dm = Channel.from_dict(await self.rest.dm(user_id))
+        self.channels[dm.id] = dm
+        return await self.send(dm.id, content, files=files, cards=cards, components=components)
+
+    async def set_commands(self, commands: list[Any]) -> list[dict[str, Any]]:
+        """Replaces all of the bot's "/" commands (they show up in the apps right away)."""
+        return await self.rest.set_commands(commands)
+
+    async def join_voice(
+        self,
+        channel_id: str,
+        *,
+        receive: bool = False,
+        relay: bool = False,
+        deaf: bool = False,
+        ffmpeg: str | None = None,
+        ytdlp: bool | str = False,
+    ) -> VoiceConnection:
+        """Joins a voice room to play (and optionally hear) audio. Needs ``zynko[voice]``.
+
+        - ``receive``: hear the room (``audio`` events with each person's sound);
+        - ``relay``: the "conexão alternativa", media only through the voice server's relay;
+        - ``deaf``: show the bot as deafened (it still plays);
+        - ``ffmpeg``, ``ytdlp``: see :class:`zynko.AudioPlayer`.
+        """
+        from .voice import VoiceConnection
+
+        if self.voice is not None and self.voice.channel_id == channel_id:
+            return self.voice
+        if self.voice is not None:
+            await self.voice.leave()
+        conn = VoiceConnection(self, channel_id, receive=receive, relay=relay, deaf=deaf, ffmpeg=ffmpeg, ytdlp=ytdlp)
+        self.voice = conn
+        try:
+            await conn.connect()
+        except BaseException:
+            if self.voice is conn:
+                self.voice = None
+            try:
+                await conn.leave()
+            except Exception:  # noqa: BLE001
+                pass
+            raise
+        return conn
+
+    def permissions_in(self, channel_id: str, user_id: str) -> Permissions:
+        """What someone may do in a channel, the server's way: @everyone and their roles, then
+        the channel's overwrites. Owners and admins may do everything."""
+        channel = self.channels.get(channel_id)
+        guild = self.guilds.get(channel.guild_id) if channel and channel.guild_id else None
+        return compute_permissions(guild, channel, user_id)
+
+    def can(self, channel_id: str, user_id: str, permission: int) -> bool:
+        """Whether someone has a permission (or all of several) in a channel."""
+        return (int(self.permissions_in(channel_id, user_id)) & int(permission)) == int(permission)
+
+    def link(self, path: str | None) -> str | None:
+        """A full link to an avatar, emoji or other ``/api/...`` path the API hands out."""
+        if not path:
+            return None
+        return path if re.match(r"^https?:", path) else self.rest.base + path
+
+    # ---------- cache ----------
+
+    def _add_guild(self, d: dict[str, Any]) -> Guild:
+        g = Guild.from_dict(d)
+        for c in g.channels.values():
+            self.channels[c.id] = c
+        for m in g.members.values():
+            self.users[m.user.id] = m.user
+        self.guilds[g.id] = g
+        return g
+
+    def _drop_guild(self, guild_id: str) -> None:
+        g = self.guilds.pop(guild_id, None)
+        if g is None:
+            return
+        for c in g.channels:
+            self.channels.pop(c, None)
+
+    def _dispatch(self, t: str, d: Any) -> None:
+        try:
+            self._handle(t, d)
+        except Exception as e:  # noqa: BLE001 - a bad event must not drop the link
+            log.exception("evento %s", t)
+            self._emit("error", e)
+
+    def _handle(self, t: str, d: Any) -> None:
+        self._emit("raw", t, d)
+        if t == "READY":
+            self.user = User.from_dict(d["user"])
+            self.session_id = d.get("session_id", "")
+            self.guilds.clear()
+            self.channels.clear()
+            self.voice_states.clear()
+            for g in d.get("guilds") or []:
+                self._add_guild(g)
+            for c in d.get("dm_channels") or []:
+                ch = Channel.from_dict(c)
+                self.channels[ch.id] = ch
+                for u in ch.recipients:
+                    self.users[u.id] = u
+            for v in d.get("voice_states") or []:
+                vs = VoiceState.from_dict(v)
+                if vs.channel_id:
+                    self.voice_states[vs.user_id] = vs
+            if self._first_ready is not None and not self._first_ready.done():
+                self._first_ready.set_result(self.user)
+            if self.voice is not None:
+                self.voice._resync()
+            self._emit("ready", self.user)
+            for g in list(self.guilds.values()):
+                self._emit("guild_create", g)
+        elif t == "GUILD_CREATE":
+            self._emit("guild_create", self._add_guild(d))
+        elif t == "GUILD_UPDATE":
+            g = self.guilds.get(d["id"])
+            if g is None:
+                return
+            g.name = d.get("name", g.name)
+            g.icon = d.get("icon")
+            g.owner_id = str(d.get("owner_id", g.owner_id))
+            self._emit("guild_update", g)
+        elif t == "GUILD_DELETE":
+            self._drop_guild(d["id"])
+            self._emit("guild_delete", d["id"])
+        elif t in ("GUILD_ROLE_CREATE", "GUILD_ROLE_UPDATE"):
+            g = self.guilds.get(d.get("guild_id", ""))
+            if g is not None:
+                r = Role.from_dict(d)
+                g.roles[r.id] = r
+        elif t == "GUILD_ROLE_DELETE":
+            g = self.guilds.get(d.get("guild_id", ""))
+            if g is not None:
+                g.roles.pop(d.get("role_id") or d.get("id"), None)
+        elif t == "GUILD_EMOJIS_UPDATE":
+            g = self.guilds.get(d.get("guild_id", ""))
+            if g is not None:
+                g.emojis = [Emoji.from_dict(e) for e in d.get("emojis") or []]
+        elif t in ("CHANNEL_CREATE", "CHANNEL_UPDATE"):
+            c = Channel.from_dict(d)
+            previous = self.channels.get(c.id)
+            if previous is not None and previous.recipients and not c.recipients:
+                c.recipients = previous.recipients
+            self.channels[c.id] = c
+            if c.guild_id and c.guild_id in self.guilds:
+                self.guilds[c.guild_id].channels[c.id] = c
+            for u in c.recipients:
+                self.users[u.id] = u
+            if t == "CHANNEL_CREATE":
+                self._emit("channel_create", c)
+                return
+            if self.voice is not None:
+                self.voice._on_channel_update(c)
+            self._emit("channel_update", c, previous)
+        elif t == "CHANNEL_DELETE":
+            c = Channel.from_dict(d)
+            self.channels.pop(c.id, None)
+            if c.guild_id and c.guild_id in self.guilds:
+                self.guilds[c.guild_id].channels.pop(c.id, None)
+            self._emit("channel_delete", c)
+        elif t in ("GUILD_MEMBER_ADD", "GUILD_MEMBER_UPDATE"):
+            m = Member.from_dict(d)
+            g = self.guilds.get(m.guild_id)
+            old_member = g.members.get(m.user.id) if g else None
+            if g is not None:
+                g.members[m.user.id] = m
+            self.users[m.user.id] = m.user
+            if t == "GUILD_MEMBER_ADD":
+                self._emit("member_add", m)
+            else:
+                self._emit("member_update", m, old_member)
+        elif t == "GUILD_MEMBER_REMOVE":
+            g = self.guilds.get(d.get("guild_id", ""))
+            if g is not None:
+                g.members.pop(d.get("user_id"), None)
+            self._emit("member_remove", d)
+        elif t == "PRESENCE_UPDATE":
+            uid = d.get("user_id")
+            for g in self.guilds.values():
+                if uid not in g.members:
+                    continue
+                if d.get("status") == "online":
+                    g.online.add(uid)
+                else:
+                    g.online.discard(uid)
+            self._emit("presence_update", d)
+        elif t == "USER_UPDATE":
+            u = User.from_dict(d)
+            self.users[u.id] = u
+            if self.user is not None and u.id == self.user.id:
+                self.user = u
+        elif t == "MESSAGE_CREATE":
+            msg = Message(self, d)
+            c = self.channels.get(msg.channel_id)
+            if c is not None:
+                c.last_message_id = msg.id
+            self.users[msg.author.id] = msg.author
+            self._emit("message_create", msg)
+        elif t == "MESSAGE_UPDATE":
+            self._emit("message_update", Message(self, d))
+        elif t == "MESSAGE_DELETE":
+            self._emit("message_delete", d)
+        elif t == "MESSAGE_REACTION_ADD":
+            self._emit("reaction_add", d)
+        elif t == "MESSAGE_REACTION_REMOVE":
+            self._emit("reaction_remove", d)
+        elif t == "TYPING_START":
+            self._emit("typing_start", d)
+        elif t == "INTERACTION_CREATE":
+            self._emit("interaction", Interaction(self, d))
+        elif t == "VOICE_STATE_UPDATE":
+            v = VoiceState.from_dict(d)
+            old_state = self.voice_states.get(v.user_id)
+            if v.channel_id:
+                self.voice_states[v.user_id] = v
+            else:
+                self.voice_states.pop(v.user_id, None)
+            if self.voice is not None and self.user is not None and v.user_id == self.user.id:
+                self.voice._on_own_state(v)
+            self._emit("voice_state_update", v, old_state)

zynko/gateway.py

@@ -0,0 +1,171 @@
+"""The realtime link (docs.zynko.org/api/gateway).
+
+HELLO, IDENTIFY with the token and the intents, heartbeats, and a fresh IDENTIFY after any
+drop (there is no RESUME: READY always brings the whole state again).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import random
+import time
+from collections.abc import Callable
+from typing import Any
+
+import aiohttp
+
+log = logging.getLogger("zynko.gateway")
+
+#: Close codes after which trying again cannot help.
+FATAL = {4004}
+
+
+def backoff(retry: int, jitter: float | None = None) -> float:
+    """Seconds to wait before reconnect number ``retry`` (0-based): 1, 2, 4... up to 30.
+
+    With some jitter (x0.75 to x1.25) so a server restart is not hit by every bot at once.
+    """
+    j = random.random() if jitter is None else jitter
+    return min(30.0, 2.0**retry) * (0.75 + j / 2)
+
+
+class GatewayClosed(Exception):
+    """The gateway refused the token: trying again cannot help."""
+
+
+class Gateway:
+    def __init__(
+        self,
+        *,
+        url: str,
+        token: str,
+        intents: int,
+        session: Callable[[], aiohttp.ClientSession],
+        on_dispatch: Callable[[str, Any], None],
+        on_state: Callable[[str, Any], None],
+    ) -> None:
+        self.url = url
+        self.token = token
+        self.intents = intents
+        self._session = session
+        self._on_dispatch = on_dispatch
+        self._on_state = on_state
+        self._ws: aiohttp.ClientWebSocketResponse[bool] | None = None
+        self._beat: asyncio.Task[None] | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._stopped = False
+        self._retry = 0
+        self._last_ack = 0.0
+
+    @property
+    def open(self) -> bool:
+        return self._ws is not None and not self._ws.closed
+
+    def start(self) -> asyncio.Task[None]:
+        """Runs the link in the background until :meth:`close`."""
+        self._stopped = False
+        if self._task is None or self._task.done():
+            self._task = asyncio.ensure_future(self._run())
+        return self._task
+
+    async def wait_closed(self) -> None:
+        if self._task is not None:
+            await asyncio.shield(self._task)
+
+    async def send(self, op: int, d: Any) -> bool:
+        """Sends an op (4: voice state). Returns whether the link was open."""
+        ws = self._ws
+        if ws is None or ws.closed:
+            return False
+        try:
+            await ws.send_str(json.dumps({"op": op, "d": d}))
+        except (ConnectionError, RuntimeError, aiohttp.ClientError):
+            return False
+        return True
+
+    async def close(self) -> None:
+        self._stopped = True
+        self._stop_beat()
+        ws, self._ws = self._ws, None
+        if ws is not None and not ws.closed:
+            await ws.close(code=1000)
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                pass
+
+    async def _run(self) -> None:
+        while not self._stopped:
+            self._on_state("reconnecting" if self._retry else "connecting", None)
+            code: int | None = None
+            reason = ""
+            try:
+                async with self._session().ws_connect(self.url, max_msg_size=0, autoping=True) as ws:
+                    self._ws = ws
+                    async for msg in ws:
+                        if msg.type == aiohttp.WSMsgType.TEXT:
+                            await self._on_message(msg.data)
+                        elif msg.type in (aiohttp.WSMsgType.ERROR, aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.CLOSING):
+                            break
+                    code = ws.close_code
+                    reason = str(ws.exception() or "")
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:  # noqa: BLE001 - any failure to connect is retried
+                reason = str(e)
+            finally:
+                self._stop_beat()
+                self._ws = None
+            if self._stopped:
+                return
+            if code in FATAL:
+                self._stopped = True
+                self._on_state("closed", GatewayClosed(f"Token recusado pelo gateway ({code} {reason})".strip()))
+                return
+            wait = backoff(self._retry)
+            self._retry += 1
+            self._on_state("reconnecting", {"code": code or 0, "reason": reason, "wait": wait})
+            await asyncio.sleep(wait)
+
+    async def _on_message(self, raw: str) -> None:
+        try:
+            msg = json.loads(raw)
+        except ValueError:
+            return
+        op = msg.get("op")
+        if op == 10:
+            await self.send(2, {"token": self.token, "intents": int(self.intents)})
+            self._stop_beat()
+            self._last_ack = time.monotonic()
+            every = ((msg.get("d") or {}).get("heartbeat_interval") or 30_000) / 1000
+            self._beat = asyncio.ensure_future(self._heartbeat(every))
+        elif op == 11:
+            self._last_ack = time.monotonic()
+        elif op == 0:
+            self._last_ack = time.monotonic()
+            t = msg.get("t")
+            if t == "READY":
+                self._retry = 0
+                self._on_state("ready", None)
+            if t:
+                self._on_dispatch(t, msg.get("d"))
+
+    async def _heartbeat(self, every: float) -> None:
+        while True:
+            await asyncio.sleep(every)
+            # No answer to two beats in a row: the link is dead even if the socket says otherwise.
+            if time.monotonic() - self._last_ack > every * 2 + 5:
+                ws = self._ws
+                if ws is not None:
+                    await ws.close(code=4900, message=b"heartbeat timeout")
+                return
+            await self.send(1, None)
+
+    def _stop_beat(self) -> None:
+        if self._beat is not None:
+            self._beat.cancel()
+        self._beat = None