slim-m 0.1.0__tar.gz

slim_m-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: slim-m
+Version: 0.1.0
+Summary: Shared plumbing for slim-m bots: auth, REST, retries, websocket reconnect, seq cursors
+License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/NC1107/slim-m
+Project-URL: Source, https://github.com/NC1107/slim-bots
+Keywords: slim-m,bots,chat
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# slimbots
+
+Shared plumbing for slim-m bot templates in this repo.
+
+This is not a typed model of slim-m's API. There is no `Channel` class, no
+`Message` object, no cache, no event hierarchy - the kind of thing a
+discord.js-shaped SDK would give you for a few hundred endpoints. slim-m's
+entire bot surface is: log in with a token, call REST, hold one websocket,
+track a per-scope `seq`. That is what this package covers:
+
+- authentication (`Authorization: Bearer`, a real `User-Agent`, `GET /me`)
+- a REST helper, `Client.call`, for any route a template needs
+- an idempotent `send` that keeps the message id fixed across a retry, and
+  retries only a genuinely uncertain failure - a network error, a 5xx, or a
+  429 - never a rejected 4xx
+- the websocket connect and hello handshake (`Connection`)
+- the reconnect loop with exponential backoff, and treating a `401` as
+  terminal rather than retryable (`run_forever`)
+- a `seq` cursor in sqlite and the `/sync` catch-up call (`cursor`)
+- refusing to carry a token over plain `ws://` to anything but a loopback
+  address (`socket_url`)
+
+It deliberately does **not** give you a typed route client, a cache, or an
+event-object hierarchy. See `docs/bots/building-bots.md` in slim-m for the
+protocol this wraps, and `bot-ping/` in this repo for the same protocol
+written out with nothing hidden - it stays free of this package on purpose,
+so there is always one template that shows the whole thing in one file.
+
+## Hand-written, not generated
+
+slim-m's wire contract is `schema/openapi.yaml`, and
+`crates/slimm-server/tests/openapi_contract.rs` already fails CI on drift, so
+a generated client would stay honest automatically. This package is
+hand-written anyway. What it wraps is not route-shaped: auth, a socket, and
+a retry policy, not a set of typed request/response pairs. A generator
+produces that badly, and slim-m already prefers hand-written DTOs and models
+on both the server and the client for the same reason. If somebody wants a
+fully typed route client later, generating one from `openapi.yaml` is a
+reasonable project - it just is not this one.
+
+## Installing
+
+The distribution is named `slim-m` on PyPI; the import stays `slimbots`.
+
+```
+pip install slim-m
+```
+
+To run against unreleased changes, install from git instead:
+
+```
+pip install "slim-m @ git+https://github.com/NC1107/slim-bots.git@main#subdirectory=slimbots"
+```
+
+Each template's `requirements.txt` pins one of those two lines.
+
+## Releasing
+
+`.github/workflows/publish.yml` builds and uploads on a published GitHub
+release, using PyPI trusted publishing - it exchanges the workflow's own
+OIDC identity for an upload token, so there is no API token stored in this
+repo. The publisher on PyPI must name this repository, `publish.yml`, and
+the `pypi` environment, or the exchange is refused.
+
+Bump `version` in `pyproject.toml`, then publish a release.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+Covers the retry policy (which errors retry, which do not, and that the
+message id and content never change across a retry), the reconnect loop's
+backoff and its terminal handling of a 401, and `socket_url`'s loopback-only
+refusal of plaintext `ws://`.

slim_m-0.1.0/README.md

@@ -0,0 +1,77 @@
+# slimbots
+
+Shared plumbing for slim-m bot templates in this repo.
+
+This is not a typed model of slim-m's API. There is no `Channel` class, no
+`Message` object, no cache, no event hierarchy - the kind of thing a
+discord.js-shaped SDK would give you for a few hundred endpoints. slim-m's
+entire bot surface is: log in with a token, call REST, hold one websocket,
+track a per-scope `seq`. That is what this package covers:
+
+- authentication (`Authorization: Bearer`, a real `User-Agent`, `GET /me`)
+- a REST helper, `Client.call`, for any route a template needs
+- an idempotent `send` that keeps the message id fixed across a retry, and
+  retries only a genuinely uncertain failure - a network error, a 5xx, or a
+  429 - never a rejected 4xx
+- the websocket connect and hello handshake (`Connection`)
+- the reconnect loop with exponential backoff, and treating a `401` as
+  terminal rather than retryable (`run_forever`)
+- a `seq` cursor in sqlite and the `/sync` catch-up call (`cursor`)
+- refusing to carry a token over plain `ws://` to anything but a loopback
+  address (`socket_url`)
+
+It deliberately does **not** give you a typed route client, a cache, or an
+event-object hierarchy. See `docs/bots/building-bots.md` in slim-m for the
+protocol this wraps, and `bot-ping/` in this repo for the same protocol
+written out with nothing hidden - it stays free of this package on purpose,
+so there is always one template that shows the whole thing in one file.
+
+## Hand-written, not generated
+
+slim-m's wire contract is `schema/openapi.yaml`, and
+`crates/slimm-server/tests/openapi_contract.rs` already fails CI on drift, so
+a generated client would stay honest automatically. This package is
+hand-written anyway. What it wraps is not route-shaped: auth, a socket, and
+a retry policy, not a set of typed request/response pairs. A generator
+produces that badly, and slim-m already prefers hand-written DTOs and models
+on both the server and the client for the same reason. If somebody wants a
+fully typed route client later, generating one from `openapi.yaml` is a
+reasonable project - it just is not this one.
+
+## Installing
+
+The distribution is named `slim-m` on PyPI; the import stays `slimbots`.
+
+```
+pip install slim-m
+```
+
+To run against unreleased changes, install from git instead:
+
+```
+pip install "slim-m @ git+https://github.com/NC1107/slim-bots.git@main#subdirectory=slimbots"
+```
+
+Each template's `requirements.txt` pins one of those two lines.
+
+## Releasing
+
+`.github/workflows/publish.yml` builds and uploads on a published GitHub
+release, using PyPI trusted publishing - it exchanges the workflow's own
+OIDC identity for an upload token, so there is no API token stored in this
+repo. The publisher on PyPI must name this repository, `publish.yml`, and
+the `pypi` environment, or the exchange is refused.
+
+Bump `version` in `pyproject.toml`, then publish a release.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+Covers the retry policy (which errors retry, which do not, and that the
+message id and content never change across a retry), the reconnect loop's
+backoff and its terminal handling of a 401, and `socket_url`'s loopback-only
+refusal of plaintext `ws://`.

slim_m-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "slim-m"
+version = "0.1.0"
+description = "Shared plumbing for slim-m bots: auth, REST, retries, websocket reconnect, seq cursors"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-PolyForm-Noncommercial-1.0.0"
+keywords = ["slim-m", "bots", "chat"]
+
+dependencies = ["websockets>=12"]
+
+[project.urls]
+Homepage = "https://github.com/NC1107/slim-m"
+Source = "https://github.com/NC1107/slim-bots"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["slimbots*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

slim_m-0.1.0/setup.cfg

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

slim_m-0.1.0/slim_m.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: slim-m
+Version: 0.1.0
+Summary: Shared plumbing for slim-m bots: auth, REST, retries, websocket reconnect, seq cursors
+License-Expression: LicenseRef-PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/NC1107/slim-m
+Project-URL: Source, https://github.com/NC1107/slim-bots
+Keywords: slim-m,bots,chat
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# slimbots
+
+Shared plumbing for slim-m bot templates in this repo.
+
+This is not a typed model of slim-m's API. There is no `Channel` class, no
+`Message` object, no cache, no event hierarchy - the kind of thing a
+discord.js-shaped SDK would give you for a few hundred endpoints. slim-m's
+entire bot surface is: log in with a token, call REST, hold one websocket,
+track a per-scope `seq`. That is what this package covers:
+
+- authentication (`Authorization: Bearer`, a real `User-Agent`, `GET /me`)
+- a REST helper, `Client.call`, for any route a template needs
+- an idempotent `send` that keeps the message id fixed across a retry, and
+  retries only a genuinely uncertain failure - a network error, a 5xx, or a
+  429 - never a rejected 4xx
+- the websocket connect and hello handshake (`Connection`)
+- the reconnect loop with exponential backoff, and treating a `401` as
+  terminal rather than retryable (`run_forever`)
+- a `seq` cursor in sqlite and the `/sync` catch-up call (`cursor`)
+- refusing to carry a token over plain `ws://` to anything but a loopback
+  address (`socket_url`)
+
+It deliberately does **not** give you a typed route client, a cache, or an
+event-object hierarchy. See `docs/bots/building-bots.md` in slim-m for the
+protocol this wraps, and `bot-ping/` in this repo for the same protocol
+written out with nothing hidden - it stays free of this package on purpose,
+so there is always one template that shows the whole thing in one file.
+
+## Hand-written, not generated
+
+slim-m's wire contract is `schema/openapi.yaml`, and
+`crates/slimm-server/tests/openapi_contract.rs` already fails CI on drift, so
+a generated client would stay honest automatically. This package is
+hand-written anyway. What it wraps is not route-shaped: auth, a socket, and
+a retry policy, not a set of typed request/response pairs. A generator
+produces that badly, and slim-m already prefers hand-written DTOs and models
+on both the server and the client for the same reason. If somebody wants a
+fully typed route client later, generating one from `openapi.yaml` is a
+reasonable project - it just is not this one.
+
+## Installing
+
+The distribution is named `slim-m` on PyPI; the import stays `slimbots`.
+
+```
+pip install slim-m
+```
+
+To run against unreleased changes, install from git instead:
+
+```
+pip install "slim-m @ git+https://github.com/NC1107/slim-bots.git@main#subdirectory=slimbots"
+```
+
+Each template's `requirements.txt` pins one of those two lines.
+
+## Releasing
+
+`.github/workflows/publish.yml` builds and uploads on a published GitHub
+release, using PyPI trusted publishing - it exchanges the workflow's own
+OIDC identity for an upload token, so there is no API token stored in this
+repo. The publisher on PyPI must name this repository, `publish.yml`, and
+the `pypi` environment, or the exchange is refused.
+
+Bump `version` in `pyproject.toml`, then publish a release.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+Covers the retry policy (which errors retry, which do not, and that the
+message id and content never change across a retry), the reconnect loop's
+backoff and its terminal handling of a 401, and `socket_url`'s loopback-only
+refusal of plaintext `ws://`.

slim_m-0.1.0/slim_m.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+slim_m.egg-info/PKG-INFO
+slim_m.egg-info/SOURCES.txt
+slim_m.egg-info/dependency_links.txt
+slim_m.egg-info/requires.txt
+slim_m.egg-info/top_level.txt
+slimbots/__init__.py
+slimbots/client.py
+slimbots/cursor.py
+slimbots/retry.py
+slimbots/runner.py
+slimbots/ws.py
+tests/test_client.py
+tests/test_cursor.py
+tests/test_retry.py
+tests/test_runner.py
+tests/test_ws.py

slim_m-0.1.0/slim_m.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

slim_m-0.1.0/slim_m.egg-info/requires.txt

@@ -0,0 +1,5 @@
+websockets>=12
+
+[dev]
+pytest
+pytest-asyncio

slim_m-0.1.0/slim_m.egg-info/top_level.txt

@@ -0,0 +1 @@
+slimbots

slim_m-0.1.0/slimbots/__init__.py

@@ -0,0 +1,29 @@
+"""Shared plumbing for slim-m bot templates.
+
+This is not a client library for slim-m's API in the discord.js sense: there
+is no typed model of a channel or a message, no cache, and no object for
+every route. slim-m's bot surface is small - log in with a token, call REST,
+hold one websocket, track a per-scope `seq` - and that surface is what this
+package covers, nothing more.
+
+See `docs/bots/building-bots.md` in the slim-m repo for the protocol itself.
+`bot-ping` in this repo stays free of this package on purpose, so there is
+still one file that shows the whole protocol with nothing hidden.
+"""
+
+from . import cursor
+from .client import Client, is_not_found, is_token_revoked, socket_url
+from .retry import call_with_retry
+from .runner import run_forever
+from .ws import Connection
+
+__all__ = [
+    "Client",
+    "Connection",
+    "call_with_retry",
+    "cursor",
+    "is_not_found",
+    "is_token_revoked",
+    "run_forever",
+    "socket_url",
+]

slim_m-0.1.0/slimbots/client.py

@@ -0,0 +1,107 @@
+"""The REST side of a bot: one authenticated call, and an idempotent send."""
+
+import json
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+from .retry import call_with_retry
+
+LOOPBACK_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+
+def socket_url(base):
+    """The WebSocket URL for `base`, refusing to carry a token in plaintext.
+
+    An https deployment becomes wss. Plain http is allowed only for a
+    loopback address, because that is a developer running a server on their
+    own machine; anywhere else it would put a long-lived bot token on the
+    wire in the clear, and a token is the one thing a bot cannot afford to
+    leak.
+    """
+    parts = urllib.parse.urlsplit(base)
+    if parts.scheme == "https":
+        return urllib.parse.urlunsplit(("wss", parts.netloc, "/ws", "", ""))
+    if parts.scheme == "http" and parts.hostname in LOOPBACK_HOSTS:
+        print("warning: plaintext ws, loopback only", file=sys.stderr)
+        return urllib.parse.urlunsplit(("ws", parts.netloc, "/ws", "", ""))
+    raise RuntimeError(
+        f"refusing to send a bot token over {parts.scheme or 'no'} scheme to "
+        f"{parts.hostname or base}; use https"
+    )
+
+
+class Client:
+    """An authenticated slim-m REST client for one bot token.
+
+    `call` is the general-purpose escape hatch: it makes no assumptions
+    about the route, so a template reaches for it directly for anything this
+    class does not name explicitly - `/sync`, canvas routes, `/users/{id}`,
+    whatever the bot needs. `send`, `me` and `ws_ticket` exist only because
+    every template calls them, byte for byte.
+    """
+
+    def __init__(self, base, token, user_agent):
+        if not base or not token:
+            raise ValueError("a Client needs both a base URL and a token")
+        self.base = base.rstrip("/")
+        self.token = token
+        self.user_agent = user_agent
+
+    def call(self, method, path, body=None):
+        """One authenticated REST call, returning parsed JSON or None for 204."""
+        data = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(f"{self.base}{path}", data=data, method=method)
+        request.add_header("authorization", f"Bearer {self.token}")
+        # A CDN can reject urllib's default UA; see docs/bots/building-bots.md.
+        request.add_header("user-agent", self.user_agent)
+        if data is not None:
+            request.add_header("content-type", "application/json")
+        with urllib.request.urlopen(request, timeout=15) as response:
+            raw = response.read()
+            return json.loads(raw) if raw else None
+
+    def me(self):
+        return self.call("GET", "/me")
+
+    def ws_ticket(self):
+        return self.call("POST", "/auth/ws-ticket")["ticket"]
+
+    def socket_url(self):
+        return socket_url(self.base)
+
+    def send(self, channel_id, content, *, message_id=None, reply_to_id=None, retries=5, sleep=time.sleep):
+        """Posts a message, retrying only a genuinely uncertain failure.
+
+        `message_id` is generated once, before any retry, and never
+        regenerated between attempts: that is what makes a retried send safe
+        rather than a second message. Never vary `content` across calls
+        sharing one `message_id` - the server replays what it first stored,
+        whatever a later attempt carries, and this method has no way to catch
+        a caller doing that. `sleep` exists for tests; a real caller never
+        needs it.
+        """
+        body = {"id": message_id or str(uuid.uuid4()), "content": content}
+        if reply_to_id:
+            body["reply_to_id"] = reply_to_id
+        return call_with_retry(
+            lambda: self.call("POST", f"/channels/{channel_id}/messages", body),
+            retries=retries,
+            sleep=sleep,
+        )
+
+
+def is_token_revoked(err):
+    """Whether `err` is the terminal 401 that means the token was revoked.
+
+    A 401 is never retried: the credential is gone, not the network. See
+    "When a token is revoked" in docs/bots/building-bots.md.
+    """
+    return isinstance(err, urllib.error.HTTPError) and err.code == 401
+
+
+def is_not_found(err):
+    return isinstance(err, urllib.error.HTTPError) and err.code == 404

slim_m-0.1.0/slimbots/cursor.py

@@ -0,0 +1,65 @@
+"""A per-channel `seq` cursor in sqlite, and the `/sync` catch-up call.
+
+This is storage and transport only. What a template does with the messages
+`/sync` hands back - which triggers fire, what state they update - stays in
+the template, because that is the part that differs bot to bot.
+
+A bot that deliberately keeps its cursor in memory instead (see bot-roles's
+README on why a command-driven bot can accept losing that on restart) has no
+reason to reach for this module at all; a plain variable is simpler and nothing
+here is missed by skipping it.
+"""
+
+
+def init_table(conn, table="cursors"):
+    conn.execute(
+        f"CREATE TABLE IF NOT EXISTS {table} "
+        "(channel_id TEXT PRIMARY KEY, after_seq INTEGER NOT NULL)"
+    )
+    conn.commit()
+
+
+def get(conn, channel_id, table="cursors"):
+    row = conn.execute(
+        f"SELECT after_seq FROM {table} WHERE channel_id = ?", (channel_id,)
+    ).fetchone()
+    return row[0] if row else None
+
+
+def set(conn, channel_id, seq, table="cursors"):
+    """Advances the stored cursor to `seq`, never backwards.
+
+    A frame handled twice (once live, once again via `/sync` after a
+    reconnect that turned out not to have dropped anything) must not move
+    the cursor earlier than where it already was.
+    """
+    conn.execute(
+        f"INSERT INTO {table} (channel_id, after_seq) VALUES (?, ?) "
+        f"ON CONFLICT(channel_id) DO UPDATE SET after_seq = excluded.after_seq "
+        f"WHERE excluded.after_seq > after_seq",
+        (channel_id, seq),
+    )
+    conn.commit()
+
+
+def bootstrap(client, conn, channel_id, table="cursors"):
+    """A channel this process has never watched starts at its current head,
+    not at the beginning of history - otherwise a bot's first minute would
+    be spent re-triggering years of old messages."""
+    if get(conn, channel_id, table) is not None:
+        return
+    latest = client.call("GET", f"/channels/{channel_id}/messages?limit=1")
+    set(conn, channel_id, latest[0]["seq"] if latest else 0, table)
+
+
+def sync(client, scopes):
+    """POSTs `/sync` for `scopes` (a list of `{"channel_id", "after_seq"}`)
+    and returns the response's own `scopes` list, one entry per input scope,
+    each carrying `messages` and a `reset` flag.
+
+    `reset: true` means the gap was too large for `/sync` to answer and the
+    cursor should be re-baselined (typically via `bootstrap`) rather than
+    trusted to resume exactly where it left off - the same tradeoff slim-m's
+    own reactions and pins accept.
+    """
+    return client.call("POST", "/sync", {"scopes": scopes})["scopes"]

slim_m-0.1.0/slimbots/retry.py

@@ -0,0 +1,40 @@
+"""Retrying a REST call, but only when the outcome is genuinely uncertain.
+
+A rejected request (a 4xx other than 429) is a certain outcome: the server
+looked at it and said no, and sending the same thing again gets the same no.
+Retrying that would be wrong, not just wasteful. What is worth retrying is a
+call whose outcome we never actually learned: a network error before any
+response came back, a 5xx (the server broke, not the request), or a 429
+(rate limited). slim-m's plain rate limit carries no `Retry-After`, so a
+fixed or exponential backoff is the only option - there is nothing to read
+that would do better.
+"""
+
+import time
+import urllib.error
+
+
+def is_retryable(err):
+    """Whether `err`, raised by `urllib.request.urlopen`, is worth another try."""
+    if isinstance(err, urllib.error.HTTPError):
+        return err.code == 429 or err.code >= 500
+    # A URLError with no `code` attribute never reached a server at all.
+    return isinstance(err, urllib.error.URLError)
+
+
+def call_with_retry(fn, *, retries=5, base_delay=0.5, max_delay=8.0, sleep=time.sleep):
+    """Calls `fn()`, retrying up to `retries` times on a retryable failure.
+
+    Backoff doubles from `base_delay`, capped at `max_delay`. `fn` must be
+    safe to call more than once with the same effect - true of any call
+    built on an idempotent id, and never true of a plain uuid4() per call.
+    """
+    attempt = 0
+    while True:
+        try:
+            return fn()
+        except (urllib.error.HTTPError, urllib.error.URLError) as err:
+            if attempt >= retries or not is_retryable(err):
+                raise
+            sleep(min(base_delay * (2**attempt), max_delay))
+            attempt += 1

slim_m-0.1.0/slimbots/runner.py

@@ -0,0 +1,38 @@
+"""The reconnect loop every template but bot-ping needs: exponential backoff,
+reset on a connection that actually completes its hello handshake, and a
+revoked token (401) as the one failure that stops the loop instead of
+retrying it.
+"""
+
+import asyncio
+import sys
+
+from .client import is_token_revoked
+
+
+async def run_forever(attempt, *, base_delay=1.0, max_delay=60.0):
+    """Calls `await attempt(reset_delay)` forever, backing off between
+    failures.
+
+    `attempt` does one connection's worth of work - typically resync, open a
+    `Connection`, call `reset_delay()` once hello succeeds, then read frames
+    until the socket drops or errors. Returns 1 once the token is found to be
+    revoked, so `main()` can propagate it as the process exit code; runs
+    until cancelled otherwise.
+    """
+    delay = base_delay
+
+    def reset_delay():
+        nonlocal delay
+        delay = base_delay
+
+    while True:
+        try:
+            await attempt(reset_delay)
+        except Exception as err:
+            if is_token_revoked(err):
+                print("token rejected - revoked?", file=sys.stderr)
+                return 1
+            print(f"{type(err).__name__}: {err}, retrying in {delay}s", file=sys.stderr)
+        await asyncio.sleep(delay)
+        delay = min(delay * 2, max_delay)

slim_m-0.1.0/slimbots/ws.py

@@ -0,0 +1,55 @@
+"""The websocket side of a bot: mint a ticket, say hello, read frames.
+
+`Connection` is deliberately thin. It does the hello handshake once and then
+gets out of the way - a frame this bot's caller does not recognise is that
+caller's job to ignore, not this module's, because a new event type must not
+break a bot that has never heard of it (see docs/bots/building-bots.md).
+"""
+
+import json
+
+import websockets
+
+PROTOCOL = 1
+
+
+class Connection:
+    """An open, hello-shaken slim-m websocket connection.
+
+    Use it as an async context manager:
+
+        async with await Connection.open(client) as conn:
+            async for frame in conn.frames():
+                ...
+    """
+
+    def __init__(self, socket):
+        self._socket = socket
+
+    @classmethod
+    async def open(cls, client, *, protocol=PROTOCOL):
+        ticket = client.ws_ticket()
+        socket = await websockets.connect(client.socket_url(), user_agent_header=client.user_agent)
+        try:
+            await socket.send(json.dumps({"type": "hello", "ticket": ticket, "protocol": protocol}))
+            hello = json.loads(await socket.recv())
+            if hello.get("type") != "hello":
+                raise RuntimeError(f"expected a hello back, got {hello}")
+        except BaseException:
+            await socket.close()
+            raise
+        return cls(socket)
+
+    async def frames(self):
+        """Yields each frame as parsed JSON, in arrival order."""
+        async for raw in self._socket:
+            yield json.loads(raw)
+
+    async def close(self):
+        await self._socket.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.close()

slim_m-0.1.0/tests/test_client.py

@@ -0,0 +1,126 @@
+import json
+import urllib.error
+
+import pytest
+
+from slimbots.client import Client, is_not_found, is_token_revoked, socket_url
+
+
+def test_https_becomes_wss():
+    assert socket_url("https://my.space") == "wss://my.space/ws"
+
+
+@pytest.mark.parametrize(
+    "authority", ["localhost:8080", "127.0.0.1:8080", "[::1]:8080"]
+)
+def test_http_loopback_allowed(authority, capsys):
+    url = socket_url(f"http://{authority}")
+    assert url == f"ws://{authority}/ws"
+    assert "loopback only" in capsys.readouterr().err
+
+
+def test_http_off_loopback_refused():
+    with pytest.raises(RuntimeError, match="https"):
+        socket_url("http://example.com")
+
+
+def test_unknown_scheme_refused():
+    with pytest.raises(RuntimeError):
+        socket_url("ftp://example.com")
+
+
+def test_client_requires_base_and_token():
+    with pytest.raises(ValueError):
+        Client("", "token", "ua")
+    with pytest.raises(ValueError):
+        Client("https://x", "", "ua")
+
+
+class FakeResponse:
+    def __init__(self, payload):
+        self._raw = json.dumps(payload).encode() if payload is not None else b""
+
+    def read(self):
+        return self._raw
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def test_call_sends_auth_and_user_agent(monkeypatch):
+    seen = {}
+
+    def fake_urlopen(request, timeout):
+        seen["headers"] = dict(request.header_items())
+        seen["url"] = request.full_url
+        seen["method"] = request.get_method()
+        return FakeResponse({"ok": True})
+
+    monkeypatch.setattr("slimbots.client.urllib.request.urlopen", fake_urlopen)
+    client = Client("https://my.space", "slimbot_abc", "slimm-bot-test/1.0")
+    result = client.call("GET", "/me")
+
+    assert result == {"ok": True}
+    assert seen["headers"]["Authorization"] == "Bearer slimbot_abc"
+    assert seen["headers"]["User-agent"] == "slimm-bot-test/1.0"
+    assert seen["url"] == "https://my.space/me"
+    assert seen["method"] == "GET"
+
+
+def test_send_keeps_id_fixed_across_a_retry(monkeypatch):
+    bodies = []
+    attempt = {"n": 0}
+
+    def fake_urlopen(request, timeout):
+        attempt["n"] += 1
+        bodies.append(json.loads(request.data))
+        if attempt["n"] < 3:
+            raise urllib.error.HTTPError(request.full_url, 503, "busy", {}, None)
+        return FakeResponse({"id": bodies[-1]["id"]})
+
+    monkeypatch.setattr("slimbots.client.urllib.request.urlopen", fake_urlopen)
+    client = Client("https://my.space", "slimbot_abc", "ua")
+    client.send("chan-1", "pong", sleep=lambda _: None)
+
+    assert attempt["n"] == 3
+    ids = {b["id"] for b in bodies}
+    contents = {b["content"] for b in bodies}
+    assert len(ids) == 1
+    assert len(contents) == 1
+
+
+def test_send_never_retries_a_rejected_4xx(monkeypatch):
+    attempt = {"n": 0}
+
+    def fake_urlopen(request, timeout):
+        attempt["n"] += 1
+        raise urllib.error.HTTPError(request.full_url, 422, "bad", {}, None)
+
+    monkeypatch.setattr("slimbots.client.urllib.request.urlopen", fake_urlopen)
+    client = Client("https://my.space", "slimbot_abc", "ua")
+    with pytest.raises(urllib.error.HTTPError):
+        client.send("chan-1", "pong")
+    assert attempt["n"] == 1
+
+
+def test_send_uses_given_message_id():
+    # This checks the body assembled, so it stubs call rather than the network.
+    client = Client("https://my.space", "slimbot_abc", "ua")
+    calls = []
+    client.call = lambda method, path, body=None: calls.append(body) or {"ok": True}
+    client.send("chan-1", "hi", message_id="fixed-id")
+    assert calls[0]["id"] == "fixed-id"
+
+
+def test_is_token_revoked():
+    assert is_token_revoked(urllib.error.HTTPError("u", 401, "e", {}, None))
+    assert not is_token_revoked(urllib.error.HTTPError("u", 403, "e", {}, None))
+    assert not is_token_revoked(urllib.error.URLError("boom"))
+
+
+def test_is_not_found():
+    assert is_not_found(urllib.error.HTTPError("u", 404, "e", {}, None))
+    assert not is_not_found(urllib.error.HTTPError("u", 401, "e", {}, None))

slim_m-0.1.0/tests/test_cursor.py

@@ -0,0 +1,82 @@
+import sqlite3
+
+import pytest
+
+from slimbots import cursor
+
+
+@pytest.fixture
+def conn():
+    connection = sqlite3.connect(":memory:")
+    cursor.init_table(connection)
+    yield connection
+    connection.close()
+
+
+def test_get_is_none_before_anything_is_set(conn):
+    assert cursor.get(conn, "chan-1") is None
+
+
+def test_set_then_get(conn):
+    cursor.set(conn, "chan-1", 10)
+    assert cursor.get(conn, "chan-1") == 10
+
+
+def test_set_never_moves_backwards(conn):
+    cursor.set(conn, "chan-1", 10)
+    cursor.set(conn, "chan-1", 5)
+    assert cursor.get(conn, "chan-1") == 10
+
+
+def test_set_advances_forward(conn):
+    cursor.set(conn, "chan-1", 10)
+    cursor.set(conn, "chan-1", 20)
+    assert cursor.get(conn, "chan-1") == 20
+
+
+def test_channels_are_independent(conn):
+    cursor.set(conn, "chan-1", 10)
+    cursor.set(conn, "chan-2", 3)
+    assert cursor.get(conn, "chan-1") == 10
+    assert cursor.get(conn, "chan-2") == 3
+
+
+class FakeClient:
+    def __init__(self, latest_seq):
+        self.calls = []
+        self._latest_seq = latest_seq
+
+    def call(self, method, path, body=None):
+        self.calls.append((method, path, body))
+        if self._latest_seq is None:
+            return []
+        return [{"seq": self._latest_seq}]
+
+
+def test_bootstrap_baselines_at_current_head_on_first_run(conn):
+    client = FakeClient(latest_seq=42)
+    cursor.bootstrap(client, conn, "chan-1")
+    assert cursor.get(conn, "chan-1") == 42
+
+
+def test_bootstrap_on_an_empty_channel_starts_at_zero(conn):
+    client = FakeClient(latest_seq=None)
+    cursor.bootstrap(client, conn, "chan-1")
+    assert cursor.get(conn, "chan-1") == 0
+
+
+def test_bootstrap_is_a_no_op_once_a_cursor_exists(conn):
+    cursor.set(conn, "chan-1", 7)
+    client = FakeClient(latest_seq=999)
+    cursor.bootstrap(client, conn, "chan-1")
+    assert cursor.get(conn, "chan-1") == 7
+    assert client.calls == []
+
+
+def test_sync_posts_scopes_and_returns_the_response_scopes():
+    client = FakeClient(latest_seq=None)
+    client.call = lambda method, path, body=None: {
+        "scopes": [{"channel_id": "chan-1", "messages": [], "reset": False}]
+    }
+    result = cursor.sync(client, [{"channel_id": "chan-1", "after_seq": 5}])
+    assert result == [{"channel_id": "chan-1", "messages": [], "reset": False}]

slim_m-0.1.0/tests/test_retry.py

@@ -0,0 +1,140 @@
+import urllib.error
+
+import pytest
+
+from slimbots.retry import call_with_retry, is_retryable
+
+
+def http_error(code):
+    return urllib.error.HTTPError("http://x", code, "err", {}, None)
+
+
+@pytest.mark.parametrize("code", [429, 500, 502, 503, 599])
+def test_retryable_codes(code):
+    assert is_retryable(http_error(code))
+
+
+@pytest.mark.parametrize("code", [400, 401, 403, 404, 409, 422])
+def test_non_retryable_4xx(code):
+    assert not is_retryable(http_error(code))
+
+
+def test_network_error_is_retryable():
+    assert is_retryable(urllib.error.URLError("connection refused"))
+
+
+def test_succeeds_without_retry():
+    calls = []
+
+    def fn():
+        calls.append(1)
+        return "ok"
+
+    assert call_with_retry(fn, sleep=lambda _: None) == "ok"
+    assert len(calls) == 1
+
+
+def test_retries_a_5xx_then_succeeds():
+    attempts = []
+
+    def fn():
+        attempts.append(1)
+        if len(attempts) < 3:
+            raise http_error(503)
+        return "ok"
+
+    result = call_with_retry(fn, retries=5, sleep=lambda _: None)
+    assert result == "ok"
+    assert len(attempts) == 3
+
+
+def test_retries_a_429_then_succeeds():
+    attempts = []
+
+    def fn():
+        attempts.append(1)
+        if len(attempts) < 2:
+            raise http_error(429)
+        return "ok"
+
+    assert call_with_retry(fn, sleep=lambda _: None) == "ok"
+    assert len(attempts) == 2
+
+
+def test_retries_a_network_error():
+    attempts = []
+
+    def fn():
+        attempts.append(1)
+        if len(attempts) < 2:
+            raise urllib.error.URLError("boom")
+        return "ok"
+
+    assert call_with_retry(fn, sleep=lambda _: None) == "ok"
+
+
+def test_never_retries_a_rejected_4xx():
+    attempts = []
+
+    def fn():
+        attempts.append(1)
+        raise http_error(400)
+
+    with pytest.raises(urllib.error.HTTPError):
+        call_with_retry(fn, sleep=lambda _: None)
+    assert len(attempts) == 1
+
+
+def test_never_retries_a_401():
+    attempts = []
+
+    def fn():
+        attempts.append(1)
+        raise http_error(401)
+
+    with pytest.raises(urllib.error.HTTPError):
+        call_with_retry(fn, sleep=lambda _: None)
+    assert len(attempts) == 1
+
+
+def test_gives_up_after_retries_exhausted():
+    attempts = []
+
+    def fn():
+        attempts.append(1)
+        raise http_error(500)
+
+    with pytest.raises(urllib.error.HTTPError):
+        call_with_retry(fn, retries=3, sleep=lambda _: None)
+    # the first attempt plus 3 retries
+    assert len(attempts) == 4
+
+
+def test_backoff_doubles_and_caps():
+    delays = []
+
+    def fn():
+        raise http_error(500)
+
+    with pytest.raises(urllib.error.HTTPError):
+        call_with_retry(
+            fn, retries=4, base_delay=1.0, max_delay=4.0, sleep=delays.append
+        )
+    assert delays == [1.0, 2.0, 4.0, 4.0]
+
+
+def test_retry_never_needs_a_new_id_or_content():
+    """The id and content a retried call sends are fixed by the caller before
+    call_with_retry ever runs; this asserts the same closure - and therefore
+    the same body - is invoked on every attempt."""
+    bodies_seen = []
+
+    def fn():
+        # A real caller closes over one fixed body; we simulate that here.
+        bodies_seen.append({"id": "fixed-id", "content": "fixed content"})
+        if len(bodies_seen) < 3:
+            raise http_error(500)
+        return bodies_seen[-1]
+
+    call_with_retry(fn, sleep=lambda _: None)
+    assert len({(b["id"], b["content"]) for b in bodies_seen}) == 1

slim_m-0.1.0/tests/test_runner.py

@@ -0,0 +1,69 @@
+import urllib.error
+
+import pytest
+
+from slimbots.runner import run_forever
+
+
+@pytest.mark.asyncio
+async def test_stops_on_a_revoked_token(monkeypatch):
+    async def fake_sleep(_):
+        pytest.fail("should not sleep after a terminal 401")
+
+    monkeypatch.setattr("slimbots.runner.asyncio.sleep", fake_sleep)
+
+    async def attempt(reset_delay):
+        raise urllib.error.HTTPError("u", 401, "e", {}, None)
+
+    assert await run_forever(attempt) == 1
+
+
+@pytest.mark.asyncio
+async def test_retries_other_failures_with_backoff(monkeypatch):
+    delays = []
+
+    async def fake_sleep(seconds):
+        delays.append(seconds)
+        if len(delays) >= 3:
+            raise SystemExit("stop the loop")
+
+    monkeypatch.setattr("slimbots.runner.asyncio.sleep", fake_sleep)
+
+    async def attempt(reset_delay):
+        raise ConnectionError("dropped")
+
+    with pytest.raises(SystemExit):
+        await run_forever(attempt, base_delay=1.0, max_delay=4.0)
+
+    assert delays == [1.0, 2.0, 4.0]
+
+
+@pytest.mark.asyncio
+async def test_a_403_is_not_terminal(monkeypatch):
+    delays = []
+
+    async def fake_sleep(seconds):
+        delays.append(seconds)
+        raise SystemExit("stop the loop")
+
+    monkeypatch.setattr("slimbots.runner.asyncio.sleep", fake_sleep)
+
+    async def attempt(reset_delay):
+        raise urllib.error.HTTPError("u", 403, "e", {}, None)
+
+    with pytest.raises(SystemExit):
+        await run_forever(attempt)
+    assert delays == [1.0]
+
+
+@pytest.mark.asyncio
+async def test_reset_delay_is_offered_to_the_attempt():
+    calls = []
+
+    async def attempt(reset_delay):
+        calls.append(reset_delay)
+        raise urllib.error.HTTPError("u", 401, "e", {}, None)
+
+    await run_forever(attempt)
+    assert len(calls) == 1
+    calls[0]()  # must not raise

slim_m-0.1.0/tests/test_ws.py

@@ -0,0 +1,102 @@
+import json
+
+import pytest
+
+from slimbots import ws as ws_module
+from slimbots.ws import Connection
+
+
+class FakeSocket:
+    def __init__(self, incoming, hello_reply=None):
+        self.sent = []
+        self.closed = False
+        self._incoming = list(incoming)
+        self._hello_reply = hello_reply if hello_reply is not None else {"type": "hello", "protocol": 1}
+
+    async def send(self, message):
+        self.sent.append(message)
+
+    async def recv(self):
+        return json.dumps(self._hello_reply)
+
+    async def close(self):
+        self.closed = True
+
+    def __aiter__(self):
+        return self._iter()
+
+    async def _iter(self):
+        for frame in self._incoming:
+            yield json.dumps(frame)
+
+
+class FakeClient:
+    def __init__(self, socket):
+        self.socket = socket
+        self.user_agent = "slimm-bot-test/1.0"
+
+    def ws_ticket(self):
+        return "ticket-123"
+
+    def socket_url(self):
+        return "wss://my.space/ws"
+
+
+@pytest.mark.asyncio
+async def test_open_sends_hello_with_ticket_and_protocol(monkeypatch):
+    socket = FakeSocket(incoming=[])
+
+    async def fake_connect(url, user_agent_header=None):
+        assert url == "wss://my.space/ws"
+        assert user_agent_header == "slimm-bot-test/1.0"
+        return socket
+
+    monkeypatch.setattr(ws_module.websockets, "connect", fake_connect)
+    conn = await Connection.open(FakeClient(socket))
+
+    sent = json.loads(socket.sent[0])
+    assert sent == {"type": "hello", "ticket": "ticket-123", "protocol": 1}
+    await conn.close()
+    assert socket.closed
+
+
+@pytest.mark.asyncio
+async def test_open_rejects_a_non_hello_reply(monkeypatch):
+    socket = FakeSocket(incoming=[], hello_reply={"type": "error"})
+
+    async def fake_connect(url, user_agent_header=None):
+        return socket
+
+    monkeypatch.setattr(ws_module.websockets, "connect", fake_connect)
+    with pytest.raises(RuntimeError, match="expected a hello"):
+        await Connection.open(FakeClient(socket))
+    # the socket must not be left open after a failed handshake
+    assert socket.closed
+
+
+@pytest.mark.asyncio
+async def test_frames_yields_parsed_json(monkeypatch):
+    frames_in = [{"type": "message.created", "n": 1}, {"type": "unknown.future.event"}]
+    socket = FakeSocket(incoming=frames_in)
+
+    async def fake_connect(url, user_agent_header=None):
+        return socket
+
+    monkeypatch.setattr(ws_module.websockets, "connect", fake_connect)
+    conn = await Connection.open(FakeClient(socket))
+
+    seen = [frame async for frame in conn.frames()]
+    assert seen == frames_in
+
+
+@pytest.mark.asyncio
+async def test_context_manager_closes_on_exit(monkeypatch):
+    socket = FakeSocket(incoming=[])
+
+    async def fake_connect(url, user_agent_header=None):
+        return socket
+
+    monkeypatch.setattr(ws_module.websockets, "connect", fake_connect)
+    async with await Connection.open(FakeClient(socket)) as conn:
+        assert conn is not None
+    assert socket.closed