msgmesh (Python SDK)
English | 繁體中文
Python SDK for MsgMesh — a publish / consume / realtime (SSE / WebSocket) / governance
client for the multi-tenant event bus. This is the Python port of the TypeScript SDK
(@msgmesh/sdk): the public API surface is
aligned, method names follow Python conventions (snake_case), and the semantics and
coverage match sdk-js. The HTTP contract's source of truth is the platform OpenAPI spec.
Upgrading from 0.6.x? No code change is required, but some behaviour differs — see Upgrading from 0.6.x.
Install
pip install msgmesh
Requires Python ≥ 3.9; the only runtime dependency is httpx
(0.27 or later, below 1.0 — httpx 1.0 is not supported yet).
Quick start
Register an account in the panel and issue an API key (shown in plaintext only once), then:
from msgmesh import MsgMesh
mq = MsgMesh(
api_key="mk_live_...", # long-lived key, server-side only
control_plane_url="https://cp.example.com",
gateway_url="https://gw.example.com",
realtime_url="https://rt.example.com",
)
mq.create_topic("orders")
mq.publish("orders", {"hello": 1})
msgs = mq.poll("orders", group="g1")
for m in msgs:
print(m.value)
MsgMesh is also a context manager and closes the underlying connection pool on exit:
with MsgMesh(api_key="mk_live_...") as mq:
mq.publish("orders", {"hello": 1})
Not for browsers / untrusted clients; mint short-lived tokens server-side
get_token mirrors the sdk-js token-broker pattern: give it a callable that fetches a
short-lived dp token from your backend (returning {"token": ..., "expires_in": ...} or a
TokenResponse). The SDK caches it, refetches before expiry, and rotates it on SSE reconnect.
It is mutually exclusive with api_key; at least one is required.
import httpx
from msgmesh import MsgMesh
def fetch_token():
return httpx.get("https://my-backend/mm-token").json() # {"token": ..., "expires_in": 300}
mq = MsgMesh(
get_token=fetch_token,
gateway_url="https://gw.example.com",
realtime_url="https://rt.example.com",
)
Realtime receive
Consistent interface — each returns a "stop" callable and runs on a background daemon thread:
-
subscribe(topic, handler, *, group=None, max=None, on_error=None): long-polling (apollloop). Terminal vs recoverable — only 401 (key invalid/missing = terminal) stops permanently; 403 (resolvable by self-service top-up), 429 and other transient errors are reported then retried with backoff (self-healing; see "Reconnect backoff" below). Inget_tokenmode a 401 is usually just an expired token: the cache is invalidated and it retries with a fresh token, only declaring permanent revocation after five consecutive rejections. The one other thing that stops it is aget_tokenthat raisesTokenUnavailableError(see "Permanent token failure" below). On permanent stop, if noon_erroris given, aloggingwarning is emitted.stop = mq.subscribe("room.42", lambda m: print(m.value), group="g1", on_error=print) # ... stop() # stop polling
-
stream(topic, on_message, on_error=None, room=None): realtime receive over SSE (connection auth via query key).on_messagereceives the text body of each event — plus itsStreamMessageMetawhen the callback declares a second parameter (see below);on_errorreceives anException(transport / non-2xx) or aStreamClose(a named server-side close event whose.datais the reason string).stop = mq.stream("room.42", print) # ... stop()
Difference from sdk-js: sdk-js
streamrelies on the browser-nativeEventSource(which auto-reconnects). Python has noEventSource, so this SDK manages reconnection itself (in the spirit of sdk-jsstreamWs): it reconnects with backoff after each stream end / connection error, rotates the token inget_tokenmode, and resets the backoff once a connection has lasted 5 seconds or delivered a message. It does not give up after a number of attempts (see "Reconnect backoff" below);"authorization revoked"is terminal and stops proactively. -
stream_ws(topic, on_message, on_error=None, room=None): realtime receive over WebSocket (connection auth via query key). Same interface asstream; needs the optional dependencywebsocket-client:pip install "msgmesh[ws]"
from msgmesh import WsClose def on_err(e): if isinstance(e, WsClose): print("closed", e.code, e.reason) # e.g. 1008 / "authorization revoked" else: print("error", e) # transport / handshake failure stop = mq.stream_ws("room.42", print, on_error=on_err) # ... stop()
This is a pure-Python server-side capability, unrelated to browsers / Node (sdk-js's
streamWsis what involves the browser / Node ≥ 22 globalWebSocket). Callingstream_wswithoutwebsocket-clientinstalled raises an immediateImportErrorwith an install hint.Difference from
stream(SSE): WebSocket has no native reconnect, so reconnection is entirely SDK-managed in both modes — backoff reconnect, reset once a connection has lasted 5 seconds or delivered a message, and no giving up after a number of attempts (see "Reconnect backoff" below);get_tokenalso rotates the token before reconnecting. Revocation: mid-connection it is CLOSE1008+"authorization revoked"(terminal, stops immediately); a refused handshake is retried with backoff like any other failure.on_errorreceives anException(transport / handshake failure) or aWsClose(a close event with readable.code/.reason);stop()ends it without triggeringon_error, and returns at once even when the peer has gone silent (it shuts the socket down instead of waiting for the peer to answer a closing handshake). If you'd rather not add the dependency,stream(SSE) orsubscribe(long-poll) cover realtime receive server-side.Reconnect backoff: it keeps trying.
subscribe,streamandstream_wsall manage their own retries. The wait between attempts starts at up to 1s and doubles with each further consecutive failure, up to 30s; the actual wait is a random value in the upper half of that ceiling, so clients that failed together do not all come back together. A success resets it to 1s: forsubscribe, a poll that returned; forstreamandstream_ws, a connection that stayed open for 5 seconds or delivered a message. Merely connecting does not count — otherwise something that accepts a connection and drops it at once would be reconnected to every second, indefinitely.streamandstream_wsdo not give up after a number of attempts: a refused connection may be a rate limit that lifts on its own (HTTP 429 — a connection limit, for instance), and stopping would leave the stream dead after the limit is gone. They end in three cases only: on the server's explicit revocation ("authorization revoked"); when you call the stop callable, which also cuts a pending wait short (and, forstream, interrupts a read that is waiting for the next event); and when yourget_tokenraisesTokenUnavailableError(below).on_erroris called on every failure, with one exception: when the server ends astream(SSE) response normally — the body simply finishes, no error — the SDK backs off and reconnects without callingon_error(stream_wshas no such silent case: it reports every connection that closes). A refused connection arrives as a typed error forstream(AuthError,RateLimitError, …) and as websocket-client's handshake exception forstream_ws, so you can stop yourself on a status you consider final. Nothing is reported once you have called the stop callable — not even a token fetch, a connection attempt or a handshake that was in flight at that moment and fails afterwards. The SDK does not do that for you, not even on a 401: on a realtime connection the platform also answers 401 while the tenant is suspended or while it cannot check the key at that moment, both of which pass. If you pass noon_error, the fifth consecutive failure logs a warning (loggermsgmesh) saying it is still retrying — once per run of consecutive failures, so a later run of five logs it again.In
get_tokenmode, end the stream yourself when the session ends. Every retry calls yourget_tokenfor a fresh token — settling at one call every 15–30 seconds for as long as nothing recovers — and the stream does not stop on its own count of failures. Once you know the credential is gone for good, do one of two things:- Call the stop callable the method returned. Nothing further is reported.
- Raise
TokenUnavailableErrorfromget_token. The SDK stops that subscription by itself and tells itson_error, once.
Permanent token failure:
TokenUnavailableError. It is the one exception yourget_tokencan raise to say "no token can be obtained any more":import httpx from msgmesh import MsgMesh, TokenUnavailableError def get_token(): r = httpx.post("https://my-backend.example/api/mm-token", headers=session_headers()) if r.status_code == 401: # your backend's way of saying the session is over raise TokenUnavailableError("signed out") r.raise_for_status() # anything else is temporary: the SDK retries return r.json() def on_error(err): if isinstance(err, TokenUnavailableError): ask_the_user_to_sign_in() # this stream has stopped and will not retry mq = MsgMesh(get_token=get_token, realtime_url="https://rt.example.com") mq.stream("room.42", print, on_error)
- Raise it when asking again cannot help: your backend answers that the user has signed out, the refresh token was rejected, the account is closed.
- Do not raise it for anything that may pass — a network error on the way to your backend, a 5xx or a 429 from it. Raise any other exception (or let the HTTP client's own error through): the SDK treats it as temporary and retries with the backoff above, exactly as it did before this exception existed.
- What the SDK does.
subscribe,streamandstream_wsstop that subscription — no further retry, no further call toget_token, and the background thread ends — and hand the exception toon_erroronce; without anon_errorthey log one warning (loggermsgmesh). A subscription whose stop callable you already called reports nothing. One-off calls (publish,history, …) raise the exception, unchanged. - It is not broadcast, and nothing is remembered. Other subscriptions on the same client
carry on until they next need a token themselves — at their own reconnect or their own next
poll — and stop then, when
get_tokenraises again. Every later need for a token callsget_tokenagain. - A subclass counts. It is a
MsgMeshError(soexcept MsgMeshErrorstill catches everything the SDK can raise) withstatus0 andcode"token_unavailable";str(err)is your message as given. Useraise TokenUnavailableError("…") from errto keep the cause. (In sdk-js the equivalent class extendsErrorand is also recognised by itsname, because a bundler can end up with two copies of that SDK; Python has no such case.)
subscribekeeps its two terminal cases (401 with an API key; five consecutive 401s inget_tokenmode) and retries everything else with the same backoff.When a 429 response says how long to wait (
retry_afterin the body first, then theRetry-Afterheader), all three wait that long if it is longer than the backoff, capped at 300s. Not every 429 says so; without it the backoff applies. For a refusedstream_wshandshake the body can be read only when the response states itsContent-Length; otherwise only the header counts. For HTTP responses the value is also on the error asRateLimitError.retry_after(Nonewhen the response did not say; never more than 86400). This is one place where the two SDKs behave differently: sdk-js'sstream/streamWssit onEventSource/WebSocket, which reveal neither the status code nor the headers of a refused connection, so there onlysubscribecan follow aRetry-After.Known limits of the reconnect logic:
- A peer that delivers one new message on every connection and then closes it resets the
backoff each round, so that loop is reconnected to about once a second — and in
get_tokenmode yourget_tokenis called just as often. A message the SDK has already seen (a resend it dedupes) does not reset it. stream: a server that accepts the connection but never sends response headers. The stop callable returns at once and nothing is reported afterwards, but the background thread stays blocked until the server answers or drops the connection (waiting for a response has no timeout, so that a quiet stream is never cut). It is a daemon thread and does not keep the process alive.
Resume on reconnect (at-least-once, no gaps). Both
stream(SSE) andstream_ws(WebSocket) resume across reconnects: each message carries a<partition>-<offset>cursor, the SDK tracks the last one seen, and on reconnect asks the server to replay from there — messages dropped during a disconnect are backfilled, not lost. Delivery is at-least-once: the SDK dedupes per-partition by cursor, so a rare overlap is suppressed rather than delivered twice. If the server can't cover the gap (older than the replay window) it emits a resync signal — passon_resyncto be told to re-fetch a snapshot. Transparent:on_messagestill receives the raw value string. (Requires the platform's realtime resume tier; against an older server it degrades to live-tail.)on_messagealso hands you the message's coordinates. Declare a second parameter and you geton_message(value, meta), wheremetais aStreamMessageMeta—id/partition/offset.meta.idis character-for-character the same<partition>-<offset>thathistory()puts on every message, so "replay history, then join the live stream" dedupes with a singlesetinstead of comparing message bodies — body comparison quietly swallows one of two genuinely identical messages ("ok" sent twice in a chat room). Backward compatible: the SDK inspects your callback and passesmetaonly when it declares a second positional parameter, so one-parameter callbacks (includingprintandlist.append) are called exactly as before.metaisNoneonly for a frame that carried no parseable cursor (a non-msgmesh server); it is still delivered.There is deliberately no
tsinmeta: the live wire carries no timestamp (an SSE frame has room for an id and the payload, nothing else), and reading the local clock would be an arrival time wearing a produce time's name. ReadHistoryMessage.tswhen you need the real timestamp.mq.stream("room.42", lambda value, meta: print(meta.id if meta else "-", value))
Rooms
A single topic can be split into multiple rooms (a room is one partition key under the hood), decoupling "number of rooms" from "number of topics". Two layers:
① Routing — publish with publish(topic, body, room=room_id) to target a room, and subscribe
with the optional room argument (same for stream / stream_ws) to receive only that room:
stop = mq.stream("chat", print, room="room-42") # only room-42 messages
stop = mq.stream_ws("chat", print, room="room-42") # WebSocket, same idea
mq.publish("chat", {"text": "hi"}, room="room-42") # publish to room-42
Omitting room = receive all messages on the topic (backward compatible). Routing only filters
— it does not enforce isolation; a malicious client can switch to someone else's room and
eavesdrop on other rooms in the same topic. For real isolation see ②.
② Isolation (platform-enforced) — add the optional rooms to a credential's capabilities
and the platform enforces that the credential can only send/receive the named rooms (403 on
overreach). rooms omitted/empty = all rooms (backward compatible); non-empty = only these. The
typical approach: the backend holds an all-rooms key and downscopes it via
POST /v1/tokens to mint a short-lived "room-42 only" token for the frontend (downscope may
only narrow, must be a subset of the key's capabilities, 403 on overreach):
import httpx
# Backend token-broker: downscope an all-rooms key to a short-lived "chat / room-42 only"
# token, returned to the frontend as get_token
def mint_room_token():
r = httpx.post(
"https://cp.example.com/v1/tokens",
headers={"Authorization": "Bearer mk_live_..."}, # backend-held all-rooms long-lived key
json={
"ttl_seconds": 600,
"capabilities": [{"ops": ["subscribe", "publish"], "topics": ["chat"], "rooms": ["room-42"]}],
},
)
return r.json() # {"token": ..., "expires_in": 600}
You can also mint a persistent room-scoped key with
create_key("key", capabilities=[{"ops": [...], "topics": [...], "rooms": [...]}]). Platform
enforcement points: subscribe (SSE/WS) must carry a ?room within the allowed set (omitting it
= wanting all rooms, also 403); the publish room must be within the allowed set.
⚠️ A room-scoped credential can only use realtime (SSE/WS) +
publishto its rooms; it cannotpoll/consume/ DLQ. Those are a whole-topic firehose (the consumer-group offset would consume other rooms; one group per room = read amplification) and can't be cleanly per-room filtered, so a room-restricted credential always gets 403 (use realtime SSE/WS ?room=). Use an unrestricted credential when you need poll/consume.
Room isolation security notes (must read)
- Isolation strength = the scope of the token you issue. Isolation only exists when the
backend downscopes an all-rooms key into a room-scoped token for the frontend. Never put
an unrestricted credential (a full key, or a token without
rooms) into the frontend / untrusted clients — that lets anyone changeroomand see all rooms, so isolation is meaningless. - The platform does not verify "who the sender is." Room isolation governs "which rooms you can send/receive," not "who you are in the room." Within a room, anyone holding that room's token can impersonate any sender in the payload. To prevent in-room impersonation: mint a token per user on the backend and stamp / verify the sender there, don't let untrusted clients self-report identity.
- Note:
presence(online count) is currently per-topic, not per-room (only leaks an aggregate number); short-lived tokens are bearer tokens — leaking one = usable for that room until TTL expires (so keep the TTL short and don't log it).
Safe retries: idempotency_key
A publish that times out leaves you guessing: did it land? Pass a unique idempotency_key (a UUID
per message is the usual choice) and you can just retry. The platform remembers the outcome for
24 hours and returns the original partition/offset instead of writing a second copy — and it does
not meter the duplicate either.
import uuid
key = str(uuid.uuid4())
mq.publish("orders", {"order_id": 1001}, idempotency_key=key)
# Timed out? Same call, same key — at most one message exists either way.
mq.publish("orders", {"order_id": 1001}, idempotency_key=key)
- One key per message. Reusing a key with a different body or room raises
ValidationError(422) rather than silently handing back the old result — otherwise the second message would vanish behind a 200. - Concurrent resend → 409. While the first attempt is still in flight, a duplicate is rejected with no side effects at all; retry a moment later to read its result.
- Best effort, not a guarantee. Delivery is at-least-once by design, and if the dedup store is briefly unavailable the platform publishes anyway rather than failing your write. Keep consumers idempotent regardless.
Client identification (User-Agent)
The SDK labels everything it sends, so the platform can tell its traffic apart from other clients':
User-Agent: msgmesh-sdk-py/<SDK version>
Pass app_info to put your own application in front of it:
mq = MsgMesh(api_key=key, app_info={"name": "order-worker", "version": "1.4.2"})
# User-Agent: order-worker/1.4.2 msgmesh-sdk-py/<SDK version> ("version" is optional)
nameandversionmust be User-Agent product tokens: letters, digits and!#$%&'*+-.^_`|~only — no spaces,/or@— and at most 128 characters each. An invalid value, a missingname, or anapp_infothat is not a mapping raisesValueErrorfrom the constructor.- The SDK's own label is
msgmesh-sdk-py; the JavaScript SDK's ismsgmesh-sdk-js. Treat them as fixed strings if you filter on them. - The header goes on every request the SDK makes: every HTTP call, the SSE connection opened by
stream, and the WebSocket handshake ofstream_ws. All of it is new in 0.7.0: up to 0.6.x, HTTP and SSE requests carried httpx's defaultUser-Agent(python-httpx/<version>) and the WebSocket handshake carried none. - Names starting with
msgmesh-are reserved for MsgMesh's own clients (msgmesh-panel,msgmesh-mcp,msgmesh-cli, and any added later) — please do not use that prefix for your application. The constructor does not reject it, but a name that is exactly one of those makes the platform count your traffic as that client's (the platform compares these names without regard to letter case). - The label is self-reported and informational. It plays no part in authentication or routing.
msgmesh.__version__is the SDK version, should you want to log it.
(sdk-js sends the same kind of label, msgmesh-sdk-js/<version>, three ways: as User-Agent
outside browsers; as an X-MsgMesh-Client header in browsers, where the User-Agent is the
browser's own; and as a client query parameter on its EventSource / WebSocket connections, which
cannot carry a header there — without the caller's appInfo, because a URL ends up in access logs.
This SDK runs server-side, where User-Agent is always available, so it uses that one header
throughout, sends neither of the other two, and never puts your app_info into a URL.)
Upgrading from 0.6.x
No code change is required, but these behave differently:
stream/stream_wsno longer stop after five consecutive failures. They used to give up; now they keep retrying with backoff (see "Reconnect backoff" above) until the server revokes the credential, you call the stop callable, orget_tokenraisesTokenUnavailableError. Inget_tokenmode every retry calls yourget_token.- Retries wait longer. The wait after a failure used to be a fixed 1s; it now doubles with
each consecutive failure, up to 30s — and all three methods (
subscribe,stream,stream_ws) wait up to 300s when a 429 response says how long. After an outage, messages can resume that much later. - The
User-Agentchanges from httpx's default (python-httpx/<version>) tomsgmesh-sdk-py/<SDK version>on every HTTP and SSE request; the WebSocket handshake ofstream_ws, which carried none, now carries it too. See "Client identification" above. - The stop callable acts at once. It interrupts a
streamread that is waiting for the next event, and forstream_wsit no longer waits for the peer to answer the closing handshake. Nothing is reported after it was called. - The
httpxrequirement now has an upper bound (httpx>=0.27,<1). httpx 1.0 changes how a client is constructed and this SDK does not work on it yet; up to 0.6.x the requirement had no upper bound, so a fresh install could pick up a 1.0 release and fail the moment a client is created. If something else you install needs httpx 1.x, the two cannot coexist: asked for both in one install, pip refuses with a dependency conflict; installed into an environment that already has httpx 1.x, pip replaces it with a 0.x release.
New in 0.7.0: TokenUnavailableError, the app_info option and RateLimitError.retry_after.
Error handling
Non-2xx responses raise a typed error by status code (all inherit MsgMeshError and carry
status/code/path/request_id):
from msgmesh import ValidationError, RateLimitError
try:
mq.create_topic("Bad Name!")
except ValidationError as e:
print("invalid argument:", e)
except RateLimitError:
print("rate limited, retry later")
| Status | Type | code |
|---|---|---|
| 400 / 422 | ValidationError |
validation |
| 401 / 403 | AuthError |
auth |
| 404 | NotFoundError |
not_found |
| 429 | RateLimitError |
rate_limit |
409 (code: operation_in_progress) |
OperationInProgressError |
operation_in_progress |
| other | MsgMeshError |
server |
| transport failure | MsgMeshConnectError |
connect |
raised by your own get_token |
TokenUnavailableError |
token_unavailable |
TokenUnavailableError never comes from the platform: you raise it from your own get_token to say no token
can be obtained any more — see "Permanent token failure" under Realtime receive. It carries status 0 —
and so does MsgMeshConnectError (the platform could not be reached), so do not read status == 0 as
"retry": tell them apart by class or by code ("token_unavailable" / "connect").
OperationInProgressError comes from dlq_replay, delete_webhook(id, dlq="purge") and delete_topic:
replaying a topic's dead letters, purging them and deleting the topic are mutually exclusive, and another one of
them is running on that topic (err.operation says which). Nothing was done — wait err.retry_after seconds and
make the same call again; do not switch to a different operation to get around it.
History: don't leave late joiners staring at a blank screen
A live stream starts at "now". Someone who opens your chat room, support thread, or event feed
after the fact sees nothing. history() fetches the most recent messages and hands you a cursor
to resume the live stream from — no gap, no duplicates.
seen = set()
def render(msg_id: str, value: str) -> None:
if msg_id in seen: # at-least-once: history and the stream deliberately overlap
return
seen.add(msg_id)
print(value)
# 1. Fetch the last 50 messages of this room (oldest → newest).
page = mm.history("chat", room="room-42", limit=50)
for m in page.messages:
render(m.id, m.value)
# 2. Resume live from where history ended, deduping by the same id. `resume_from` was
# replayable when it was issued.
mm.stream("chat", lambda value, meta: render(meta.id, value) if meta else print(value),
room="room-42", resume_from=page.resume_from or None)
Two cursors, two meanings — this is the part people get wrong:
| field | what it is for | guarantee |
|---|---|---|
resume_from |
pass to stream / stream_ws as resume_from |
it was inside the replayable window when the response was produced |
before |
pass back to history for the previous page |
none — never hand it to stream |
Two details about resume_from that save debugging time later:
- It is not necessarily the
idof the last message you received. The scan runs newest → oldest, so the server already knows the range above your newest message holds nothing for this room, and it advances the cursor there on purpose — that leaves the largest possible margin for however long your app takes to open the stream. resume_gap=Truemeans resuming would skip messages: you paged further back than the replayable window, retention deleted the middle, or this was a whole-topic (noroom) query on a multi-partition topic. When it isFalse, nothing is skipped — the server only reports a gap it actually has.
Paging further back:
cursor = page.before
while cursor:
older = mm.history("chat", room="room-42", limit=50, before=cursor)
for m in older.messages:
render(m.id, m.value)
cursor = older.before # "" = nothing older
That loop terminates: before enumerates every partition the scan covered, so each round strictly
moves back and no page is ever repeated.
complete=True means the scan stopped because it satisfied your request — it either filled the
page to limit, or it reached the bottom of what exists. It is not "the page was filled to
limit", and it is not "there is nothing older". A room with only 3 messages answers a
limit=50 query with complete=True and 3 messages; so does a busy room answering with a full page
of 50 while thousands more sit further back.
To find out whether there is another page, read before, never complete. A non-empty before
means more is reachable; "" means you have reached the bottom. (limit is silently capped
server-side, so len(messages) < limit is not a reliable end-of-history test either.)
complete=False means the scan was cut short by something other than your request, and
incomplete_reason says by what: budget (the older messages are still in Kafka, this scan just
did not reach them — page back with before; it covers the bounded record scan, the per-page byte
cap, and a stalled broker) or retention (you passed a since bound reaching further back than the
platform still keeps; that stretch is deleted for good — you only ever see this when you asked for a
specific older range, a plain "latest N" query is always complete=True). The difference that
matters: budget is recoverable by paging, retention is not.
Timestamps in before / since are epoch milliseconds (or RFC3339). Passing epoch seconds
is rejected with 400 rather than silently answering about 1970 — pass a datetime and the SDK
gets it right for you (naive datetimes are treated as UTC).
What this is, and is not. Under the hood this is a bounded scan over the event log, not a
separate history database. Two consequences worth designing around: how far back you can reach is
capped by your plan's retention period, and passing room is dramatically cheaper than
scanning the whole topic (a room lives on a single partition). If you need audit-grade access to
messages older than your retention window, keep your own copy.
The SDK stores nothing. Where a cursor belongs — memory, a file, your own backend — is your
app's decision. Keep resume_from wherever fits and pass it back next time.
API overview (mapped to sdk-js)
Method names are sdk-js camelCase → Python snake_case; return types are dataclasses
(attribute access, e.g. topic.name).
- Topics:
create_topic/list_topics/delete_topic - Send/receive:
publish(optionalroom+idempotency_keyfor safe retries) /poll/subscribe(polling) /stream(SSE) /stream_ws(WebSocket, optionalmsgmesh[ws]) /get_presence/history(recent messages + a cursor to resume the live stream from) - Keys:
list_keys/create_key(with optionalscope+capabilities) /delete_key - Webhooks:
list_webhooks/create_webhook(new webhooks only receive messages published after creation unless you passfrom_="start") /update_webhook(change the URL in place — no resend; use it instead of delete + create) /delete_webhook(deleting a webhook that leaves no other active webhook on the topic while its DLQ holds messages raisesDLQNotEmptyError; retry withdlq="keep"ordlq="purge"— purge raisesDLQPurgeBlockedErrorwhile the topic still has suspended webhooks, seeerr.suspended_siblings) /reactivate_webhook - Schemas:
register_schema/list_schemas/get_latest_schema/delete_schema - Functions:
register_function/get_function/delete_function(JavaScript / WASM) - Plan:
get_plan/set_plan; usage:get_usage - Settings:
get_settings/set_strict_topics(data-plane topic gate toggle) - Billing (crypto PAYG prepaid):
get_billing/get_deposit_addresses/get_deposits/get_ledger/get_usage_debits/get_deposit_status - Misc:
get_snippet/get_docs/get_audit, DLQget_dlq_depth(read-only count) /dlq_peek/dlq_replay(fix or recreate the webhook before replaying)
Optional capability:
stream_ws(WebSocket) is provided via the optional dependencywebsocket-client(pip install msgmesh[ws]); the base install doesn't include it and other features are unaffected. Server-side, SSE (stream) + long-poll (subscribe) are also available. Registration and admin go through panel sessions, not this SDK.
Design notes
- HTTP client uses
httpx: it supports both regular requests and streaming (SSE), fitting this SDK's realtime needs; it's more modern thanrequests(typing, streaming context managers) and nicer thanurllib. You can pass atransport(httpx.BaseTransport) into the constructor to stub it for tests, mirroring sdk-js'sfetchImpl. - Synchronous API: no async for now; background loops (
subscribe/stream) run on daemon threads and return a stop callable.
Development
pip install -e ".[dev]"
pytest
Publishing (maintainers)
Publishing runs via GitHub Actions (.github/workflows/release-sdk-py.yml), authenticated with a
PyPI API token stored as the repo secret PYPI_API_TOKEN.
- Bump the version: change both
[project].versioninpyproject.tomland__version__insrc/msgmesh/__init__.pyto the new version (the two must match). - Merge to master.
- Tag and push:
git tag sdk-py-v<version>(e.g.sdk-py-v0.1.0) →git push origin sdk-py-v<version>. The workflow then builds (python -m build) + tests (pytest) +twine check+ publishes to PyPI.
An already-published version fails (never clobbers a released version). The sdk-py-v* tag prefix
is exclusive to this package and doesn't collide with the npm packages' sdk-v* / mcp-v* /
cli-v*.
msgmesh (Python SDK) · 繁體中文
English | 繁體中文
MsgMesh 的 Python SDK — 多租戶事件總線的收發 / 即時(SSE / WebSocket)/ 治理 client。
這是 TypeScript SDK(@msgmesh/sdk)的 Python 移植版:
對外 API 面對齊,方法名採 Python 慣例(snake_case),語意/涵蓋範圍與 sdk-js 一致。HTTP 契約
以平台 OpenAPI(packages/shared-go/openapi/openapi.yaml)為權威來源。
從 0.6.x 升級? 程式不必改,但有些行為不同了——見從 0.6.x 升級。
安裝
pip install msgmesh
需要 Python ≥ 3.9;唯一執行期依賴為 httpx(0.27 以上、1.0 以下——還不支援 httpx 1.0)。
快速開始
先在面板註冊帳號、簽發一把 API key(明文僅顯示一次),再:
from msgmesh import MsgMesh
mq = MsgMesh(
api_key="mk_live_...", # 伺服器端用長期 key
control_plane_url="https://cp.example.com",
gateway_url="https://gw.example.com",
realtime_url="https://rt.example.com",
)
mq.create_topic("orders")
mq.publish("orders", {"hello": 1})
msgs = mq.poll("orders", group="g1")
for m in msgs:
print(m.value)
MsgMesh 也是 context manager,離開時關閉底層連線池:
with MsgMesh(api_key="mk_live_...") as mq:
mq.publish("orders", {"hello": 1})
瀏覽器/不可信端不適用;伺服器代拿短期 token
get_token 對應 sdk-js 的 token-broker 模式:給一個「去後端拿短期 dp token」的 callable
(回傳 {"token": ..., "expires_in": ...} 或 TokenResponse),SDK 會自動快取、將過期前重取,
SSE 重連時亦換新。與 api_key 二擇一,至少需其一。
import httpx
from msgmesh import MsgMesh
def fetch_token():
return httpx.get("https://my-backend/mm-token").json() # {"token": ..., "expires_in": 300}
mq = MsgMesh(
get_token=fetch_token,
gateway_url="https://gw.example.com",
realtime_url="https://rt.example.com",
)
即時接收
介面一致、皆回傳「停止用 callable」,並在背景 daemon thread 執行:
-
subscribe(topic, handler, *, group=None, max=None, on_error=None):長輪詢(poll迴圈)。 終態 vs 可恢復——只有 401(金鑰失效/不存在=終態)才永久停止;403(可自助充值解封)、429 與其他 暫時性錯誤回報後退避續試(自癒;見下方「重連退避」)。get_token模式的 401 多半只是 token 過期,失效快取後以新 token 續試,連續 5 次仍被拒才判定永久撤權。另一個會讓它停止的情況是get_token丟出TokenUnavailableError(見下方「永久拿不到 token」)。永久停止時若未提供on_error,會記一則loggingwarning。stop = mq.subscribe("room.42", lambda m: print(m.value), group="g1", on_error=print) # ... stop() # 停止輪詢
-
stream(topic, on_message, on_error=None, room=None):透過 SSE 即時接收(連線鑑權走 query key)。on_message收到每則事件的文字內容——回呼若宣告第二個參數,還會收到該則的StreamMessageMeta(見下);on_error收到Exception(連線層/非 2xx)或StreamClose(伺服器具名關閉事件,.data為原因字串)。stop = mq.stream("room.42", print) # ... stop()
與 sdk-js 的差異:sdk-js 的
stream依賴瀏覽器原生EventSource(有原生自動重連)。 Python 無EventSource,故本 SDK 自管重連(對齊 sdk-jsstreamWs的精神):每次串流結束/ 連線錯誤退避後重連,get_token模式換新 token,連線撐過 5 秒或收到訊息後退避歸零。不會因為試了幾次就放棄 (見下方「重連退避」);"authorization revoked"為終態,主動停止。 -
stream_ws(topic, on_message, on_error=None, room=None):透過 WebSocket 即時接收(連線鑑權走 query key)。 介面與stream一致;需選用依賴websocket-client:pip install "msgmesh[ws]"
from msgmesh import WsClose def on_err(e): if isinstance(e, WsClose): print("closed", e.code, e.reason) # 例如 1008 / "authorization revoked" else: print("error", e) # 連線層 / 握手失敗 stop = mq.stream_ws("room.42", print, on_error=on_err) # ... stop()
這是純 Python 伺服器端能力,與瀏覽器 / Node 無關(sdk-js 的
streamWs才涉及瀏覽器/Node ≥ 22 的全域WebSocket)。未安裝websocket-client時呼叫stream_ws會立即ImportError附安裝提示。與
stream(SSE)的差異:WebSocket 無原生重連,故重連一律由 SDK 接管(兩種模式皆然)——退避重連、 連線撐過 5 秒或收到訊息後歸零、不會因為試了幾次就放棄(見下方「重連退避」),get_token另在重連前換新 token。撤權:連線中為 CLOSE1008+"authorization revoked"(終態,立即停); 握手被拒則與其他失敗一樣退避重試。on_error收到Exception(連線層/握手失敗) 或WsClose(關閉事件,可讀.code/.reason);stop()主動結束不觸發on_error, 對端已經沒有回應時也會立刻返回(直接關掉 socket,不等對端回應關閉握手)。 不想加依賴時,伺服器端用stream(SSE)或subscribe(長輪詢)即可覆蓋即時接收。
重連退避:會一直試下去。 subscribe、stream、stream_ws 的重試都由 SDK 自己管。等待時間從最多 1 秒起,
每多連續失敗一次就加倍,上限 30 秒;實際等待是該級距上半段裡的隨機值,所以同時失敗的一批客戶端不會同時回來。
成功一次就歸零回到 1 秒:subscribe 是一次輪詢有回應;stream 與 stream_ws 是連線撐過 5 秒、或收到一則訊息。
光是「連上」不算——否則遇到一接受連線就馬上關掉的對象,會變成每秒重連一次、沒完沒了。
stream 與 stream_ws 不會因為試了幾次就放棄:連線被拒可能只是過一陣子會自己解除的限流(HTTP 429,
例如連線數上限),這時停下來,限制解除後串流也不會回來。它們只在三種情況結束:伺服器明確撤權
("authorization revoked");你呼叫停止用 callable(它也會立刻中斷等待中的重試,stream 正在等下一則事件的讀取
也會被打斷);以及你的 get_token 丟出 TokenUnavailableError(見下)。
每次失敗都會呼叫 on_error,只有一種情況例外:伺服器把 stream(SSE)的回應正常結束時——內文單純收完、
沒有錯誤——SDK 會退避後重連,但不呼叫 on_error(stream_ws 沒有這種安靜的情況:連線每次被關都會回報)。
連線被拒時,stream 收到的是有型別的錯誤(AuthError、RateLimitError…),
stream_ws 收到的是 websocket-client 的握手例外,你認定某個狀態碼是終態時可以自己停。
呼叫停止用 callable 之後就不再回報任何東西——當下還在進行中的取 token、連線或握手,事後才失敗也一樣。SDK 不會替你停,
401 也不會:在即時連線上,租戶停權中、或平台當下無法查核這把 key 時,回的同樣是 401,而這兩種情況都會過去。
沒給 on_error 時,連續第 5 次失敗會記一則 warning(logger msgmesh)說明它還在重試——每一輪連續失敗各記一則,
所以之後若又連續失敗 5 次會再記。
get_token 模式下,工作階段結束時請自己把串流結束掉。 每次重試都會向你的 get_token 要一張新 token
——一直沒恢復的話,最後穩定在每 15–30 秒呼叫一次——而串流不會因為失敗了幾次就自己停。確定憑證已經失效時,
請用下面兩種做法之一:
- 呼叫停止用 callable(該方法的回傳值)。之後不再回報任何東西。
- 讓
get_token丟出TokenUnavailableError。 SDK 會自己把那個訂閱停掉,並通知它的on_error一次。
永久拿不到 token:TokenUnavailableError。 你的 get_token 用它表示「之後也換不到 token 了」:
import httpx
from msgmesh import MsgMesh, TokenUnavailableError
def get_token():
r = httpx.post("https://my-backend.example/api/mm-token", headers=session_headers())
if r.status_code == 401: # 你的後端用這個回應表示工作階段已經結束
raise TokenUnavailableError("signed out")
r.raise_for_status() # 其他狀況都是暫時性的:SDK 會重試
return r.json()
def on_error(err):
if isinstance(err, TokenUnavailableError):
ask_the_user_to_sign_in() # 這條串流已經停止,不會再重試
mq = MsgMesh(get_token=get_token, realtime_url="https://rt.example.com")
mq.stream("room.42", print, on_error)
- 什麼時候該丟: 再問一次也沒有用的時候——你的後端回覆使用者已登出、refresh token 被拒、帳號已關閉。
- 什麼時候不該丟: 任何可能過去的狀況——連不上你的後端的網路錯誤、後端回的 5xx 或 429。這時丟其他任何例外 (或讓 HTTP 用戶端自己的錯誤直接往外丟):SDK 會當成暫時性的,照上面的退避重試,與加入這個例外之前完全相同。
- SDK 會做什麼:
subscribe、stream、stream_ws會把那個訂閱停掉——不再重試、不再呼叫get_token、 背景執行緒結束——並把這個例外交給on_error一次;沒給on_error時記一則 warning(loggermsgmesh)。 已經呼叫過停止用 callable 的訂閱不會回報。一次性的呼叫(publish、history…)則是原樣丟出這個例外。 - 不廣播,也不記住。 同一個用戶端上的其他訂閱會繼續運作,直到它們自己下一次需要 token——各自重連、
或各自下一次輪詢——那時
get_token再丟一次,它們才停。之後每一次需要 token,SDK 都會再呼叫get_token。 - 子類別也算。它是
MsgMeshError(所以except MsgMeshError仍然接得到 SDK 會丟的所有例外),status為 0、code為"token_unavailable";str(err)就是你給的訊息原文。要保留原因請用raise TokenUnavailableError("…") from err。(sdk-js 的對應類別繼承的是Error,而且另外認name, 因為打包工具可能把那個 SDK 打包成兩份;Python 沒有這種情況。)
subscribe 保留兩個終態(API key 的 401;get_token 模式連續 5 次 401),其餘錯誤都以同一套退避重試。
429 的回應有說要等多久時(先看內文的 retry_after,再看 Retry-After 標頭),若比退避值長,三者都會等那麼久
(上限 300 秒)。不是每個 429 都會帶;沒帶就照退避走。stream_ws 握手被拒時,回應要有 Content-Length
才讀得到內文,否則只看標頭。HTTP 回應的這個值也掛在錯誤上:RateLimitError.retry_after
(回應沒給時為 None;最多 86400)。這是兩個 SDK 行為不同的一處:sdk-js 的 stream / streamWs 架在
EventSource / WebSocket 上,連線被拒時拿不到狀態碼與標頭,所以它只有 subscribe 能照 Retry-After 等。
重連邏輯的已知限制:
- 對方每條連線都先送一則新訊息、再把連線關掉時,每一輪都會歸零,所以這種迴圈大約每秒重連一次;
get_token模式下你的get_token也會被呼叫得一樣頻繁。SDK 已經看過的訊息(被去重的重送)不會讓它歸零。 stream:伺服器收下連線卻一直不回應標頭。 停止用 callable 會立刻返回、之後也不會回報任何東西, 但背景執行緒會卡到伺服器回應或斷線為止(等回應這一段沒有逾時,安靜的串流才不會被切斷)。 它是 daemon 執行緒,不會撐住行程。
on_message 同時給你這則訊息的座標。 回呼多宣告一個參數就會收到 on_message(value, meta),
meta 為 StreamMessageMeta(id / partition / offset)。meta.id 與 history() 每則訊息上的
<partition>-<offset> 逐字相同,這正是「先回放歷史、再接即時流」能只用一個 set 去重的原因——
否則只能拿內容硬比,而兩則內容一模一樣的訊息(聊天室裡連送兩次「ok」)會被誤吞一則。
向後相容:SDK 會內省你的回呼,只有宣告了第二個位置參數才帶 meta,故既有只吃一個參數的回呼
(含 print、list.append)呼叫方式完全不變。只有當該則訊息沒帶得出可解析的游標時(非 msgmesh 伺服器)
meta 才是 None,而訊息照樣投遞。
meta 刻意沒有 ts:即時線上根本不帶時間戳(SSE 一則事件只放得下 id 與 payload),
在客戶端補一個當下時鐘,等於把「到達時間」冠上「產生時間」的名字。需要真時間戳請讀 HistoryMessage.ts。
mq.stream("room.42", lambda value, meta: print(meta.id if meta else "-", value))
多房間(rooms)
一個 topic 內可再切多個房間(底層就是一個分割鍵),脫鉤「房間數」與「topic 數」。分兩層:
① 路由——發佈時用 publish(topic, body, room=room_id) 指定房間,訂閱時傳選用 room(stream /
stream_ws 皆同)只收該房間:
stop = mq.stream("chat", print, room="room-42") # 只收 room-42 的訊息
stop = mq.stream_ws("chat", print, room="room-42") # WebSocket 同理
mq.publish("chat", {"text": "hi"}, room="room-42") # 發到 room-42
省略 room=收該 topic 全部訊息(向後相容)。路由本身只做過濾、無強制隔離——惡意 client 可改成別人的
room 偷聽同 topic 其他房間。要真隔離看 ②。
② 隔離(平台強制)——把憑證的 capabilities 加上選用 rooms,平台即強制該憑證只能收發指定房間
(逾越 403)。rooms 省略/空 = 所有房間(向後相容);非空 = 僅限這些。典型作法是後端持一把全房間金鑰,
向 POST /v1/tokens 降權簽出「只准某房間」的短期 token 給前端(降權只准更窄、須為金鑰能力子集,逾越 403):
import httpx
# 後端 token-broker:用全房間 key 降權鑄「只准 chat / room-42」的短期 token,回給前端當 get_token
def mint_room_token():
r = httpx.post(
"https://cp.example.com/v1/tokens",
headers={"Authorization": "Bearer mk_live_..."}, # 後端持有的全房間長期 key
json={
"ttl_seconds": 600,
"capabilities": [{"ops": ["subscribe", "publish"], "topics": ["chat"], "rooms": ["room-42"]}],
},
)
return r.json() # {"token": ..., "expires_in": 600}
也可用 create_key("key", capabilities=[{"ops": [...], "topics": [...], "rooms": [...]}]) 簽一把常駐
room-scoped 鍵。平台強制點:訂閱(SSE/WS)必須帶允許集內的 ?room(不帶=想收全部房間,一樣 403);
發佈的 room 必須 ∈ 允許集。
⚠️ room-scoped 憑證只能走即時(SSE/WS)+ 對其房間
publish;不能poll/consume/ DLQ。 後者是整個 topic 的 firehose(consumer-group offset 會吃掉別房間、每房一 group = 讀取放大),無法乾淨 per-room 過濾,受限房間憑證一律 403(use realtime SSE/WS ?room=)。需要 poll/consume 時請改用不限房間的憑證。
房間隔離的安全須知(必讀)
- 隔離強度 = 你發的 token 範圍。 只有在「後端用全房間金鑰降權鑄 room-scoped token 給前端」時才有隔離。別把不限房間的憑證(全權 key、或沒有
rooms的 token)放進前端 / 不可信端——那樣對方改個room就能看到所有房間,隔離形同虛設。 - 平台不驗「發訊者是誰」。 房間隔離管的是「能收發哪些房間」,不是「你是房裡的誰」。同一房內,任何持該房 token 的人都能在 payload 裡冒充任何 sender。要防房內冒名:後端為每個使用者各自鑄 token、並由後端戳上 / 驗證 sender,別讓不可信端自報身分。
- 附帶:
presence(在線數)目前是 per-topic 非 per-room(只洩漏聚合數字);短期 token 為 bearer,洩漏 = 該房 ≤TTL 可用(故 TTL 短、勿記進 log)。
安全重送:idempotency_key
publish 逾時的當下你是沒有答案的:到底送出去了沒?帶一把唯一的 idempotency_key(慣例是每則訊息一個 UUID)就可以直接重送——平台會記住這把鍵 24 小時,同鍵重送直接回原本的 partition/offset,不會寫進第二份,也不會重複計量。
import uuid
key = str(uuid.uuid4())
mq.publish("orders", {"order_id": 1001}, idempotency_key=key)
# 逾時了?同一個呼叫、同一把鍵再送一次——不論如何最多只會存在一則。
mq.publish("orders", {"order_id": 1001}, idempotency_key=key)
- 一則訊息一把鍵。 同鍵配不同 body/room 會拋
ValidationError(422),而不是靜默把舊結果還給你——否則第二則訊息會躲在 200 後面憑空消失。 - 併發重送回 409。 前一次還在進行中時,重送直接被擋,沒有任何副作用;稍後再試就能讀到它的結果。
- 是輔助,不是保證。 平台的投遞語意本來就是 at-least-once;去重服務短暫不可用時會選擇照常發布,而不是讓你的寫入失敗。消費端仍要能容忍重複。
用戶端標記(User-Agent)
SDK 會替自己送出的東西加上標記,讓平台分得出它與其他用戶端的流量:
User-Agent: msgmesh-sdk-py/<SDK 版號>
傳入 app_info,就會把你的應用程式放在前面:
mq = MsgMesh(api_key=key, app_info={"name": "order-worker", "version": "1.4.2"})
# User-Agent: order-worker/1.4.2 msgmesh-sdk-py/<SDK 版號> ("version" 可省略)
name與version必須是 User-Agent 的 product token:只能有英數字與!#$%&'*+-.^_`|~, 不能有空白、/或@;長度各自最多 128 個字元。不合法、沒給name、或app_info不是 mapping 時, 建構子會拋ValueError。- 這個 SDK 自報的名稱是
msgmesh-sdk-py;JavaScript SDK 是msgmesh-sdk-js。要依它們篩選時,請當成固定字串。 - SDK 發出的每個請求都帶:每個 HTTP 呼叫、
stream開的 SSE 連線、stream_ws的 WebSocket 握手。 這些都是 0.7.0 新增的:0.6.x 以前,HTTP 與 SSE 請求帶的是 httpx 預設的User-Agent(python-httpx/<版號>), WebSocket 握手不帶User-Agent。 msgmesh-開頭的名稱是保留的,只給 MsgMesh 自己的用戶端用(msgmesh-panel、msgmesh-mcp、msgmesh-cli, 以及日後新增的)——請不要拿這個前綴當你的應用程式名稱。建構子不會擋,但名稱剛好是其中之一時, 平台會把你的流量算成那個用戶端的(平台比對這些名稱時不分大小寫)。- 標記是用戶端自己報的、只供參考,不參與鑑權,也不影響路由。
- 需要記錄 SDK 版號時用
msgmesh.__version__。
(sdk-js 的同一種標記 msgmesh-sdk-js/<版號> 走三條路:瀏覽器以外用 User-Agent;瀏覽器裡的 User-Agent
是瀏覽器自己的,所以改用 X-MsgMesh-Client 標頭;EventSource / WebSocket 連線在瀏覽器裡帶不了標頭,
所以放在網址的 client 參數——那裡不含呼叫端的 appInfo,因為網址會進存取紀錄。本 SDK 只跑在伺服器端,
User-Agent 一律可用,因此全程只用這一個標頭,另外兩種都不送,你的 app_info 也不會出現在任何網址上。)
從 0.6.x 升級
程式不必改,但下列行為不同了:
stream/stream_ws不再因為連續失敗 5 次而停止。 以前會放棄;現在會照退避一直重試(見上面的「重連退避」), 直到伺服器撤權、你呼叫停止用 callable,或get_token丟出TokenUnavailableError。get_token模式下每次重試都會呼叫你的get_token。- 重試的間隔變長了。 失敗後的等待以前固定 1 秒;現在每多連續失敗一次就加倍,上限 30 秒
——三個方法(
subscribe、stream、stream_ws)遇到有說要等多久的 429 時最長等 300 秒。 服務恢復之後,訊息可能晚這麼久才回來。 User-Agent變了。 每個 HTTP 與 SSE 請求從 httpx 的預設值(python-httpx/<版號>)變成msgmesh-sdk-py/<SDK 版號>;stream_ws的 WebSocket 握手以前不帶,現在也帶。見上面的「用戶端標記」。- 停止用 callable 立刻生效。 它會打斷
stream正在等下一則事件的讀取;對stream_ws, 不再等對端回應關閉握手。呼叫之後不再回報任何東西。 httpx的版本範圍加了上限(httpx>=0.27,<1)。httpx 1.0 改了 client 的建立方式,這個 SDK 還不能在上面跑; 0.6.x 以前沒有設上限,全新安裝可能裝到 1.0、一建立 client 就出錯。你的環境若另外需要 httpx 1.x,兩者不能並存: 同一次安裝同時要求兩者時,pip 會回報依賴衝突而拒絕;裝進已經有 httpx 1.x 的環境時,pip 會把它換成 0.x 的版本。
0.7.0 新增:TokenUnavailableError、app_info 選項、RateLimitError.retry_after。
錯誤處理
非 2xx 回應會依狀態碼拋型別化錯誤(都繼承 MsgMeshError,帶 status/code/path/request_id):
from msgmesh import ValidationError, RateLimitError
try:
mq.create_topic("Bad Name!")
except ValidationError as e:
print("參數不合法:", e)
except RateLimitError:
print("被限流,稍後重試")
| 狀態碼 | 型別 | code |
|---|---|---|
| 400 / 422 | ValidationError |
validation |
| 401 / 403 | AuthError |
auth |
| 404 | NotFoundError |
not_found |
| 429 | RateLimitError |
rate_limit |
409(code: operation_in_progress) |
OperationInProgressError |
operation_in_progress |
| 其他 | MsgMeshError |
server |
| 連線層失敗 | MsgMeshConnectError |
connect |
你自己的 get_token 丟的 |
TokenUnavailableError |
token_unavailable |
TokenUnavailableError 不會來自平台:它是由你自己的 get_token 丟出來、表示「之後也換不到 token 了」的例外
——見「即時接收」裡的「永久拿不到 token」。它的 status 是 0;連不上平台時的 MsgMeshConnectError 也是 0,
所以不要看到 status == 0 就重試——用類別或 code("token_unavailable" / "connect")分辨。
OperationInProgressError 來自 dlq_replay、delete_webhook(id, dlq="purge") 與 delete_topic:同一個 topic 的
重放死信、清除死信、刪 topic 三者互斥,另一個正在進行(err.operation 說明是哪一種)。什麼都沒做——等
err.retry_after 秒後再呼叫同一個方法即可;不要改用其他操作繞過。
歷史訊息:別讓晚到的人面對一片空白
即時串流是從「現在」開始的。晚一步打開聊天室、工單、事件流的人,看到的是空的。
history() 取回最近的訊息,並交給你一個游標,讓你無縫接上即時串流——不漏、不重複。
seen = set()
def render(msg_id: str, value: str) -> None:
if msg_id in seen: # at-least-once:歷史與串流刻意有重疊,依 id 去重
return
seen.add(msg_id)
print(value)
# 1. 取這個房間最近 50 則(由舊到新)。
page = mm.history("chat", room="room-42", limit=50)
for m in page.messages:
render(m.id, m.value)
# 2. 從歷史的結尾接上即時,並用同一個 id 去重。resume_from 在發出的當下必定可續傳。
mm.stream("chat", lambda value, meta: render(meta.id, value) if meta else print(value),
room="room-42", resume_from=page.resume_from or None)
兩個游標語意不同——這是最容易搞錯的地方:
| 欄位 | 用途 | 保證 |
|---|---|---|
resume_from |
交給 stream / stream_ws 的 resume_from |
在回應產生的當下必定落在可續傳窗內 |
before |
交回 history 取更舊的一頁 |
沒有——絕對不要拿去餵 stream |
關於 resume_from,兩個之後會省你除錯時間的細節:
- 它不一定等於你收到的最後一則的
id。掃描是由新到舊的,伺服器已經知道「你最新那一則之上」 那段沒有這個房間的訊息,於是刻意把游標推到那裡——讓你的 app 從「拿到歷史」到「連上串流」 之間的容忍時間最大化。 resume_gap=True代表續傳真的會漏掉一段:你往回翻得比可續傳窗還舊、中間被保留期刪掉, 或這是多 partition 的全 topic(不帶room)查詢。為False時就是沒有漏。
往前翻頁:
cursor = page.before
while cursor:
older = mm.history("chat", room="room-42", limit=50, before=cursor)
for m in older.messages:
render(m.id, m.value)
cursor = older.before # "" = 沒有更舊的了
這個迴圈保證會結束:before 會列出本次掃描的每一個 partition,故每一圈都嚴格往舊推進、
不會重複回同一頁。
complete=True 代表掃描是因為滿足了你的請求才停的——裝滿了 limit 則,或已經掃到底。
它不是「這一頁裝滿了 limit 則」,也不是「沒有更舊的了」。一個總共只有 3 則的房間查 limit=50,
回的是 complete=True 加 3 則;一個很忙的房間回了滿滿 50 則、後面還有幾千則,同樣是 complete=True。
要知道還有沒有下一頁,看 before,不要看 complete。 before 非空代表還拿得到更舊的,
"" 代表已經到底了。(limit 在伺服器端有上限、超過時不會報錯,所以 len(messages) < limit
同樣不能拿來判斷歷史是否到底。)
complete=False 代表掃描是被你的請求以外的原因打斷的,incomplete_reason 說明是哪一種:
budget(更舊的還在 Kafka 裡,只是這次沒掃到,帶 before 再翻一頁;涵蓋則數掃描、單頁位元組
上限、broker 一時卡住三種)、retention(你帶的 since 範圍比平台還留著的更舊,那一段已經被刪掉、
拿不回來;只有指定了某段較舊的範圍才會遇到,單純「最近 N 則」的查詢一律是 complete=True)。
差別在可否補救:budget 翻頁就有,retention 沒了就是沒了。
before / since 的時間是 epoch 毫秒(或 RFC3339)。傳成 epoch 秒會回 400,
而不是默默回答 1970 年的事——直接傳 datetime(naive 視為 UTC),SDK 會幫你轉對。
它是什麼、不是什麼:底下是對事件日誌的有界回掃,不是獨立的歷史資料庫。兩個要納入設計的
結果:能回溯多遠受方案保留期約束;帶 room 遠比掃整個 topic 便宜(一個 room 落在單一 partition)。
需要稽核等級地存取保留期以外的訊息,請自行留存副本。
SDK 不替你保存任何東西:游標該放哪裡(記憶體、檔案、你自己的後端)是你的 app 的決定。
API 一覽(對照 sdk-js)
方法名為 sdk-js 的 camelCase → Python snake_case,回傳型別為 dataclass(屬性存取,如 topic.name)。
- Topics:
create_topic/list_topics/delete_topic - 收發:
publish(可帶room與idempotency_key安全重送)/poll/subscribe(輪詢)/stream(SSE)/stream_ws(WebSocket,選用msgmesh[ws])/get_presence/history(最近訊息 + 接回即時串流的游標) - Keys:
list_keys/create_key(可帶scope+capabilities)/delete_key - Webhooks:
list_webhooks/create_webhook(新 webhook 預設只收建立之後的訊息,要補送歷史帶from_="start")/update_webhook(就地改網址,不重送;改網址用它,不要刪除重建)/delete_webhook(刪掉之後 topic 上沒有其他 active webhook、而 DLQ 還有死信時拋DLQNotEmptyError,帶dlq="keep"或dlq="purge"重送;topic 上還有停權中的 webhook 時(err.suspended_siblings> 0)purge 會拋DLQPurgeBlockedError,只能 keep)/reactivate_webhook - Schemas:
register_schema/list_schemas/get_latest_schema/delete_schema - Functions:
register_function/get_function/delete_function(JavaScript / WASM) - 方案:
get_plan/set_plan;用量:get_usage - 設定:
get_settings/set_strict_topics(資料面 topic 閘門開關) - 帳務(加密貨幣 PAYG 預付):
get_billing/get_deposit_addresses/get_deposits/get_ledger/get_usage_debits/get_deposit_status - 其他:
get_snippet/get_docs/get_audit、DLQget_dlq_depth(唯讀筆數)/dlq_peek/dlq_replay(先修好或重建 webhook 再重放)
選用能力:
stream_ws(WebSocket)透過選用依賴websocket-client(pip install msgmesh[ws])提供; base 安裝不含此依賴、也不影響其他功能。伺服器端另有 SSE(stream)+ 長輪詢(subscribe)可用。 註冊、超管走面板 session,不在本 SDK。
設計說明
- HTTP client 用
httpx:同時支援一般請求與串流(SSE),契合本 SDK 的即時需求;比requests更現代(型別、streaming context manager),且較urllib好用。可在建構式傳入transport(httpx.BaseTransport)以打樁測試,對應 sdk-js 的fetchImpl。 - 同步 API:先不做 async;背景迴圈(
subscribe/stream)以 daemon thread 執行並回傳停止 callable。
開發
pip install -e ".[dev]"
pytest
發布(維護者)
發布走 GitHub Actions(.github/workflows/release-sdk-py.yml),認證用存於 repo secret
PYPI_API_TOKEN 的 PyPI API token。
- bump 版本:
pyproject.toml的[project].version與src/msgmesh/__init__.py的__version__一起改成新版號(兩處需一致)。 - 合併 master。
- 打 tag 並 push:
git tag sdk-py-v<版本>(如sdk-py-v0.1.0)→git push origin sdk-py-v<版本>。 workflow 隨即 build(python -m build)+ test(pytest)+twine check+ 發布到 PyPI。
版本已存在於 PyPI 會 fail(不覆蓋已發版本)。tag 前綴 sdk-py-v* 為本套件專屬,不與 npm 套件的
sdk-v* / mcp-v* / cli-v* 撞車。
Metadata
Release files for msgmesh 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| msgmesh-0.7.0.tar.gz | 94.0 kB | Without provenance | Details for msgmesh-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| msgmesh-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for msgmesh-0.7.0-py3-none-any.whl |
Total release size: 166.2 kB
Release files / msgmesh-0.7.0.tar.gz
| Download URL | msgmesh-0.7.0.tar.gz |
|---|---|
| Size | 94.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e67720292b72289696999a5eb833712480296a504a02c4df1f9ead5dc7760933
|
|
BLAKE2b-256 checksum How to use checksums |
1d06fc8689e83cf2d3c5e094cf7261e7b2d04c2157369202ca99c80d5a872275
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / msgmesh-0.7.0-py3-none-any.whl
| Download URL | msgmesh-0.7.0-py3-none-any.whl |
|---|---|
| Size | 72.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19d2b6d4ecdeed0652941759719bfd0309756ebb7a683961bf2f4a4827323299
|
|
BLAKE2b-256 checksum How to use checksums |
196d4bc6ebcfb3f249d1e24d0f0e8c9f862a82d1e1ab218c284b8d15e47dd8e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for msgmesh 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.