magic-campus-im 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. magic_campus_im-0.1.0/MANIFEST.in +1 -0
  2. magic_campus_im-0.1.0/PKG-INFO +70 -0
  3. magic_campus_im-0.1.0/README.md +55 -0
  4. magic_campus_im-0.1.0/magic_campus_im.egg-info/PKG-INFO +70 -0
  5. magic_campus_im-0.1.0/magic_campus_im.egg-info/SOURCES.txt +36 -0
  6. magic_campus_im-0.1.0/magic_campus_im.egg-info/dependency_links.txt +1 -0
  7. magic_campus_im-0.1.0/magic_campus_im.egg-info/requires.txt +8 -0
  8. magic_campus_im-0.1.0/magic_campus_im.egg-info/top_level.txt +1 -0
  9. magic_campus_im-0.1.0/magiccampus_im/__init__.py +9 -0
  10. magic_campus_im-0.1.0/magiccampus_im/_transport/__init__.py +1 -0
  11. magic_campus_im-0.1.0/magiccampus_im/_transport/gob_codec.py +289 -0
  12. magic_campus_im-0.1.0/magiccampus_im/_transport/group_info_api.py +47 -0
  13. magic_campus_im-0.1.0/magiccampus_im/_transport/http_api.py +58 -0
  14. magic_campus_im-0.1.0/magiccampus_im/_transport/media.py +839 -0
  15. magic_campus_im-0.1.0/magiccampus_im/_transport/models.py +645 -0
  16. magic_campus_im-0.1.0/magiccampus_im/_transport/proto/__init__.py +21 -0
  17. magic_campus_im-0.1.0/magiccampus_im/_transport/proto/sdkws/__init__.py +1 -0
  18. magic_campus_im-0.1.0/magiccampus_im/_transport/proto/sdkws/sdkws_pb2.py +215 -0
  19. magic_campus_im-0.1.0/magiccampus_im/_transport/proto/wrapperspb/__init__.py +1 -0
  20. magic_campus_im-0.1.0/magiccampus_im/_transport/proto/wrapperspb/wrapperspb_pb2.py +45 -0
  21. magic_campus_im-0.1.0/magiccampus_im/_transport/self_user_info_api.py +182 -0
  22. magic_campus_im-0.1.0/magiccampus_im/_transport/storage.py +128 -0
  23. magic_campus_im-0.1.0/magiccampus_im/_transport/text.py +75 -0
  24. magic_campus_im-0.1.0/magiccampus_im/_transport/ws_client.py +1670 -0
  25. magic_campus_im-0.1.0/magiccampus_im/auth.py +111 -0
  26. magic_campus_im-0.1.0/magiccampus_im/client.py +351 -0
  27. magic_campus_im-0.1.0/magiccampus_im/errors.py +18 -0
  28. magic_campus_im-0.1.0/magiccampus_im/reaction_api.py +110 -0
  29. magic_campus_im-0.1.0/pyproject.toml +24 -0
  30. magic_campus_im-0.1.0/scripts/prepare_channel_handoff.py +52 -0
  31. magic_campus_im-0.1.0/setup.cfg +4 -0
  32. magic_campus_im-0.1.0/tests/test_client_lifecycle.py +127 -0
  33. magic_campus_im-0.1.0/tests/test_handoff.py +54 -0
  34. magic_campus_im-0.1.0/tests/test_im_quote_message.py +58 -0
  35. magic_campus_im-0.1.0/tests/test_im_send_message_content.py +104 -0
  36. magic_campus_im-0.1.0/tests/test_message_encoding.py +273 -0
  37. magic_campus_im-0.1.0/tests/test_recovery.py +434 -0
  38. magic_campus_im-0.1.0/tests/test_self_user_info.py +165 -0
@@ -0,0 +1 @@
1
+ include scripts/prepare_channel_handoff.py
@@ -0,0 +1,70 @@
1
+ Metadata-Version: 2.4
2
+ Name: magic-campus-im
3
+ Version: 0.1.0
4
+ Summary: Magic Campus channel communication SDK
5
+ License-Expression: AGPL-3.0-or-later
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: httpx<1,>=0.27
9
+ Requires-Dist: protobuf<7,>=6.32.0
10
+ Requires-Dist: websocket-client<2,>=1.8.0
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest>=8; extra == "dev"
13
+ Requires-Dist: build>=1; extra == "dev"
14
+ Requires-Dist: twine>=6; extra == "dev"
15
+
16
+ # magic-campus-im
17
+
18
+ Channel-only communication SDK. It has no CLI, business clients, group-management
19
+ methods or public history/synchronization API. HTTP is retained for IM credentials,
20
+ profiles, media upload and channel reactions. It does not depend on either business
21
+ distribution.
22
+
23
+ ```python
24
+ from magiccampus_im import MagicCampusWSConfig, MagicCampusWSSDK
25
+
26
+ sdk = MagicCampusWSSDK(
27
+ MagicCampusWSConfig(apiurl="https://campus.example", apikey="...", data_dir="./channel-state"),
28
+ on_recv_new_message=handle_message,
29
+ on_recv_offline_new_message=handle_recovered_message,
30
+ )
31
+ sdk.login()
32
+ sdk.start()
33
+ # sdk.send_text("hello", recv_id="...")
34
+ # sdk.add_message_reaction(...), sdk.delete_message_reaction(...)
35
+ # sdk.logout() closes connection and state storage
36
+ ```
37
+
38
+ ## Receive recovery
39
+
40
+ A new installation establishes a current receive baseline, without pulling old
41
+ history. `auto_sync_on_connect=False` skips previously missed messages on startup;
42
+ set it to true to resume existing checkpoints after a process restart or controlled
43
+ handoff. `auto_sync_on_reconnect=True` recovers gaps after a connection interruption.
44
+ These switches control internal recovery only; there is no public `sync_once`.
45
+
46
+ Recovery pages are delivered through `on_recv_offline_new_message`. Live pushes are
47
+ buffered during recovery and deduplicated against recovered messages. A live push
48
+ ahead of the snapshot cannot advance the checkpoint over a gap. The startup
49
+ baseline is established once per connection, so retrying cannot skip later messages.
50
+ Each successful callback atomically records its message ID and receive cursor;
51
+ a failed callback leaves that message unacknowledged. Acknowledged sequences are
52
+ not replayed after the bounded ID cache is evicted.
53
+
54
+ Errors are reported through `on_error` and recovery retries use the configured
55
+ backoff/attempt limit. A failed conversation does not prevent healthy conversations
56
+ from recovering or receiving live messages. Server minimum-sequence and confirmed
57
+ range boundaries are honored when supplied. Unavailable sequences are reported as
58
+ recovery gaps; only server-confirmed progress is skipped. An absent/unconfirmed
59
+ range remains pending rather than silently advancing its cursor. Stop wakes pending
60
+ requests, and workers/sockets from an old connection cannot commit into a new one.
61
+
62
+ `channel-progress_<user>.db` stores only checkpoints, initialization state and a
63
+ bounded set of message IDs (10,000). It contains no searchable chat bodies. State
64
+ belongs to one user/environment/platform data directory. Its metadata binds the
65
+ endpoint/user/platform context and rejects a mismatched context; token rotation
66
+ keeps the same context. Do not share a directory between unrelated instances. Callbacks must return successfully to record
67
+ receipt. This is not an acknowledgment that an Agent finished processing a message.
68
+
69
+ The implementation uses the existing OpenIM protocol. Real server retention and
70
+ notification behavior still require staging validation before online migration.
@@ -0,0 +1,55 @@
1
+ # magic-campus-im
2
+
3
+ Channel-only communication SDK. It has no CLI, business clients, group-management
4
+ methods or public history/synchronization API. HTTP is retained for IM credentials,
5
+ profiles, media upload and channel reactions. It does not depend on either business
6
+ distribution.
7
+
8
+ ```python
9
+ from magiccampus_im import MagicCampusWSConfig, MagicCampusWSSDK
10
+
11
+ sdk = MagicCampusWSSDK(
12
+ MagicCampusWSConfig(apiurl="https://campus.example", apikey="...", data_dir="./channel-state"),
13
+ on_recv_new_message=handle_message,
14
+ on_recv_offline_new_message=handle_recovered_message,
15
+ )
16
+ sdk.login()
17
+ sdk.start()
18
+ # sdk.send_text("hello", recv_id="...")
19
+ # sdk.add_message_reaction(...), sdk.delete_message_reaction(...)
20
+ # sdk.logout() closes connection and state storage
21
+ ```
22
+
23
+ ## Receive recovery
24
+
25
+ A new installation establishes a current receive baseline, without pulling old
26
+ history. `auto_sync_on_connect=False` skips previously missed messages on startup;
27
+ set it to true to resume existing checkpoints after a process restart or controlled
28
+ handoff. `auto_sync_on_reconnect=True` recovers gaps after a connection interruption.
29
+ These switches control internal recovery only; there is no public `sync_once`.
30
+
31
+ Recovery pages are delivered through `on_recv_offline_new_message`. Live pushes are
32
+ buffered during recovery and deduplicated against recovered messages. A live push
33
+ ahead of the snapshot cannot advance the checkpoint over a gap. The startup
34
+ baseline is established once per connection, so retrying cannot skip later messages.
35
+ Each successful callback atomically records its message ID and receive cursor;
36
+ a failed callback leaves that message unacknowledged. Acknowledged sequences are
37
+ not replayed after the bounded ID cache is evicted.
38
+
39
+ Errors are reported through `on_error` and recovery retries use the configured
40
+ backoff/attempt limit. A failed conversation does not prevent healthy conversations
41
+ from recovering or receiving live messages. Server minimum-sequence and confirmed
42
+ range boundaries are honored when supplied. Unavailable sequences are reported as
43
+ recovery gaps; only server-confirmed progress is skipped. An absent/unconfirmed
44
+ range remains pending rather than silently advancing its cursor. Stop wakes pending
45
+ requests, and workers/sockets from an old connection cannot commit into a new one.
46
+
47
+ `channel-progress_<user>.db` stores only checkpoints, initialization state and a
48
+ bounded set of message IDs (10,000). It contains no searchable chat bodies. State
49
+ belongs to one user/environment/platform data directory. Its metadata binds the
50
+ endpoint/user/platform context and rejects a mismatched context; token rotation
51
+ keeps the same context. Do not share a directory between unrelated instances. Callbacks must return successfully to record
52
+ receipt. This is not an acknowledgment that an Agent finished processing a message.
53
+
54
+ The implementation uses the existing OpenIM protocol. Real server retention and
55
+ notification behavior still require staging validation before online migration.
@@ -0,0 +1,70 @@
1
+ Metadata-Version: 2.4
2
+ Name: magic-campus-im
3
+ Version: 0.1.0
4
+ Summary: Magic Campus channel communication SDK
5
+ License-Expression: AGPL-3.0-or-later
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: httpx<1,>=0.27
9
+ Requires-Dist: protobuf<7,>=6.32.0
10
+ Requires-Dist: websocket-client<2,>=1.8.0
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest>=8; extra == "dev"
13
+ Requires-Dist: build>=1; extra == "dev"
14
+ Requires-Dist: twine>=6; extra == "dev"
15
+
16
+ # magic-campus-im
17
+
18
+ Channel-only communication SDK. It has no CLI, business clients, group-management
19
+ methods or public history/synchronization API. HTTP is retained for IM credentials,
20
+ profiles, media upload and channel reactions. It does not depend on either business
21
+ distribution.
22
+
23
+ ```python
24
+ from magiccampus_im import MagicCampusWSConfig, MagicCampusWSSDK
25
+
26
+ sdk = MagicCampusWSSDK(
27
+ MagicCampusWSConfig(apiurl="https://campus.example", apikey="...", data_dir="./channel-state"),
28
+ on_recv_new_message=handle_message,
29
+ on_recv_offline_new_message=handle_recovered_message,
30
+ )
31
+ sdk.login()
32
+ sdk.start()
33
+ # sdk.send_text("hello", recv_id="...")
34
+ # sdk.add_message_reaction(...), sdk.delete_message_reaction(...)
35
+ # sdk.logout() closes connection and state storage
36
+ ```
37
+
38
+ ## Receive recovery
39
+
40
+ A new installation establishes a current receive baseline, without pulling old
41
+ history. `auto_sync_on_connect=False` skips previously missed messages on startup;
42
+ set it to true to resume existing checkpoints after a process restart or controlled
43
+ handoff. `auto_sync_on_reconnect=True` recovers gaps after a connection interruption.
44
+ These switches control internal recovery only; there is no public `sync_once`.
45
+
46
+ Recovery pages are delivered through `on_recv_offline_new_message`. Live pushes are
47
+ buffered during recovery and deduplicated against recovered messages. A live push
48
+ ahead of the snapshot cannot advance the checkpoint over a gap. The startup
49
+ baseline is established once per connection, so retrying cannot skip later messages.
50
+ Each successful callback atomically records its message ID and receive cursor;
51
+ a failed callback leaves that message unacknowledged. Acknowledged sequences are
52
+ not replayed after the bounded ID cache is evicted.
53
+
54
+ Errors are reported through `on_error` and recovery retries use the configured
55
+ backoff/attempt limit. A failed conversation does not prevent healthy conversations
56
+ from recovering or receiving live messages. Server minimum-sequence and confirmed
57
+ range boundaries are honored when supplied. Unavailable sequences are reported as
58
+ recovery gaps; only server-confirmed progress is skipped. An absent/unconfirmed
59
+ range remains pending rather than silently advancing its cursor. Stop wakes pending
60
+ requests, and workers/sockets from an old connection cannot commit into a new one.
61
+
62
+ `channel-progress_<user>.db` stores only checkpoints, initialization state and a
63
+ bounded set of message IDs (10,000). It contains no searchable chat bodies. State
64
+ belongs to one user/environment/platform data directory. Its metadata binds the
65
+ endpoint/user/platform context and rejects a mismatched context; token rotation
66
+ keeps the same context. Do not share a directory between unrelated instances. Callbacks must return successfully to record
67
+ receipt. This is not an acknowledgment that an Agent finished processing a message.
68
+
69
+ The implementation uses the existing OpenIM protocol. Real server retention and
70
+ notification behavior still require staging validation before online migration.
@@ -0,0 +1,36 @@
1
+ MANIFEST.in
2
+ README.md
3
+ pyproject.toml
4
+ magic_campus_im.egg-info/PKG-INFO
5
+ magic_campus_im.egg-info/SOURCES.txt
6
+ magic_campus_im.egg-info/dependency_links.txt
7
+ magic_campus_im.egg-info/requires.txt
8
+ magic_campus_im.egg-info/top_level.txt
9
+ magiccampus_im/__init__.py
10
+ magiccampus_im/auth.py
11
+ magiccampus_im/client.py
12
+ magiccampus_im/errors.py
13
+ magiccampus_im/reaction_api.py
14
+ magiccampus_im/_transport/__init__.py
15
+ magiccampus_im/_transport/gob_codec.py
16
+ magiccampus_im/_transport/group_info_api.py
17
+ magiccampus_im/_transport/http_api.py
18
+ magiccampus_im/_transport/media.py
19
+ magiccampus_im/_transport/models.py
20
+ magiccampus_im/_transport/self_user_info_api.py
21
+ magiccampus_im/_transport/storage.py
22
+ magiccampus_im/_transport/text.py
23
+ magiccampus_im/_transport/ws_client.py
24
+ magiccampus_im/_transport/proto/__init__.py
25
+ magiccampus_im/_transport/proto/sdkws/__init__.py
26
+ magiccampus_im/_transport/proto/sdkws/sdkws_pb2.py
27
+ magiccampus_im/_transport/proto/wrapperspb/__init__.py
28
+ magiccampus_im/_transport/proto/wrapperspb/wrapperspb_pb2.py
29
+ scripts/prepare_channel_handoff.py
30
+ tests/test_client_lifecycle.py
31
+ tests/test_handoff.py
32
+ tests/test_im_quote_message.py
33
+ tests/test_im_send_message_content.py
34
+ tests/test_message_encoding.py
35
+ tests/test_recovery.py
36
+ tests/test_self_user_info.py
@@ -0,0 +1,8 @@
1
+ httpx<1,>=0.27
2
+ protobuf<7,>=6.32.0
3
+ websocket-client<2,>=1.8.0
4
+
5
+ [dev]
6
+ pytest>=8
7
+ build>=1
8
+ twine>=6
@@ -0,0 +1 @@
1
+ magiccampus_im
@@ -0,0 +1,9 @@
1
+ """Channel communication SDK. History browsing and group administration are excluded."""
2
+ from .client import MagicCampusWSConfig, MagicCampusWSSDK
3
+ from .auth import MagicCampusCredentials
4
+ from ._transport.models import WSMessage, SelfUserInfo, ContentType
5
+ from ._transport.text import parse_at_text_markup
6
+
7
+ __version__ = "0.1.0"
8
+ __all__ = ["MagicCampusWSConfig", "MagicCampusWSSDK", "MagicCampusCredentials", "WSMessage",
9
+ "SelfUserInfo", "ContentType", "parse_at_text_markup", "__version__"]
@@ -0,0 +1 @@
1
+ """Private OpenIM transport implementation."""
@@ -0,0 +1,289 @@
1
+ import struct
2
+ import re
3
+ from dataclasses import dataclass
4
+ from typing import Any, Dict, List, Optional, Tuple
5
+
6
+
7
+ # This frame defines the wire type for:
8
+ # type GeneralWsReq struct {
9
+ # ReqIdentifier int
10
+ # Token string
11
+ # SendID string
12
+ # OperationID string
13
+ # MsgIncr string
14
+ # Data []byte
15
+ # }
16
+ #
17
+ # Generated from Go encoding/gob and kept as a stable bootstrap frame.
18
+ REQ_TYPE_DEF_FRAME = bytes.fromhex(
19
+ "657f0301010c47656e6572616c577352657101ff80000106010d5265714964656e7469666965720104000105546f6b656e010c00010653656e644944010c00010b4f7065726174696f6e4944010c0001074d7367496e6372010c00010444617461010a000000"
20
+ )
21
+
22
+ # We use remote type id 64 for outbound GeneralWsReq.
23
+ REQ_TYPE_ID = 64
24
+
25
+
26
+ class GobDecodeError(ValueError):
27
+ pass
28
+
29
+
30
+ RESP_FIELD_ORDER_OBSERVED = ["ReqIdentifier", "MsgIncr", "OperationID", "ErrCode", "ErrMsg", "Data"]
31
+ RESP_FIELD_ORDER_LEGACY = ["ReqIdentifier", "ErrCode", "ErrMsg", "MsgIncr", "OperationID", "Data"]
32
+ RESP_FIELD_ORDER_CANDIDATES = [RESP_FIELD_ORDER_OBSERVED, RESP_FIELD_ORDER_LEGACY]
33
+
34
+
35
+ def encode_uint(x: int) -> bytes:
36
+ if x < 0:
37
+ raise ValueError("uint cannot be negative")
38
+ if x <= 0x7F:
39
+ return bytes([x])
40
+ n = (x.bit_length() + 7) // 8
41
+ first = (256 - n) & 0xFF
42
+ return bytes([first]) + x.to_bytes(n, byteorder="big", signed=False)
43
+
44
+
45
+ def decode_uint(data: bytes, offset: int = 0) -> Tuple[int, int]:
46
+ if offset >= len(data):
47
+ raise GobDecodeError("unexpected end while decoding uint")
48
+ b0 = data[offset]
49
+ if b0 <= 0x7F:
50
+ return b0, offset + 1
51
+ n = (-struct.unpack("b", bytes([b0]))[0])
52
+ if n <= 0:
53
+ raise GobDecodeError("invalid uint length")
54
+ end = offset + 1 + n
55
+ if end > len(data):
56
+ raise GobDecodeError("unexpected end while decoding uint body")
57
+ return int.from_bytes(data[offset + 1 : end], byteorder="big", signed=False), end
58
+
59
+
60
+ def encode_int(i: int) -> bytes:
61
+ if i < 0:
62
+ u = ((~i) << 1) | 1
63
+ else:
64
+ u = i << 1
65
+ return encode_uint(u)
66
+
67
+
68
+ def decode_int(data: bytes, offset: int = 0) -> Tuple[int, int]:
69
+ u, off = decode_uint(data, offset)
70
+ if u & 1:
71
+ return (~(u >> 1)), off
72
+ return (u >> 1), off
73
+
74
+
75
+ def _encode_string(s: str) -> bytes:
76
+ b = s.encode("utf-8")
77
+ return encode_uint(len(b)) + b
78
+
79
+
80
+ def _decode_string(data: bytes, offset: int) -> Tuple[str, int]:
81
+ ln, off = decode_uint(data, offset)
82
+ end = off + ln
83
+ if end > len(data):
84
+ raise GobDecodeError("unexpected end while decoding string")
85
+ return data[off:end].decode("utf-8", errors="replace"), end
86
+
87
+
88
+ def _encode_bytes(b: bytes) -> bytes:
89
+ return encode_uint(len(b)) + b
90
+
91
+
92
+ def _decode_bytes(data: bytes, offset: int) -> Tuple[bytes, int]:
93
+ ln, off = decode_uint(data, offset)
94
+ end = off + ln
95
+ if end > len(data):
96
+ raise GobDecodeError("unexpected end while decoding bytes")
97
+ return data[off:end], end
98
+
99
+
100
+ def _encode_general_ws_req_struct(req: Dict[str, Any]) -> bytes:
101
+ # field numbering in Go struct order
102
+ # 0 ReqIdentifier int
103
+ # 1 Token string
104
+ # 2 SendID string
105
+ # 3 OperationID string
106
+ # 4 MsgIncr string
107
+ # 5 Data []byte
108
+ out = bytearray()
109
+ last_field = -1
110
+
111
+ def emit_field(field_num: int, payload: bytes) -> None:
112
+ nonlocal last_field
113
+ delta = field_num - last_field
114
+ out.extend(encode_uint(delta))
115
+ out.extend(payload)
116
+ last_field = field_num
117
+
118
+ req_identifier = int(req.get("ReqIdentifier", 0) or 0)
119
+ token = str(req.get("Token", "") or "")
120
+ send_id = str(req.get("SendID", "") or "")
121
+ operation_id = str(req.get("OperationID", "") or "")
122
+ msg_incr = str(req.get("MsgIncr", "") or "")
123
+ data = req.get("Data", b"")
124
+ if not isinstance(data, (bytes, bytearray)):
125
+ raise ValueError("Data must be bytes")
126
+ data = bytes(data)
127
+
128
+ if req_identifier != 0:
129
+ emit_field(0, encode_int(req_identifier))
130
+ if token:
131
+ emit_field(1, _encode_string(token))
132
+ if send_id:
133
+ emit_field(2, _encode_string(send_id))
134
+ if operation_id:
135
+ emit_field(3, _encode_string(operation_id))
136
+ if msg_incr:
137
+ emit_field(4, _encode_string(msg_incr))
138
+ if data:
139
+ emit_field(5, _encode_bytes(data))
140
+
141
+ out.extend(encode_uint(0)) # struct terminator
142
+ return bytes(out)
143
+
144
+
145
+ def encode_general_ws_req_stream(req: Dict[str, Any], include_type_def: bool) -> bytes:
146
+ chunks: List[bytes] = []
147
+ if include_type_def:
148
+ chunks.append(REQ_TYPE_DEF_FRAME)
149
+ value_body = encode_int(REQ_TYPE_ID) + _encode_general_ws_req_struct(req)
150
+ chunks.append(encode_uint(len(value_body)) + value_body)
151
+ return b"".join(chunks)
152
+
153
+
154
+ @dataclass
155
+ class GobFrame:
156
+ type_id: int
157
+ is_type_def: bool
158
+ payload: bytes
159
+
160
+
161
+ def split_gob_frames(stream: bytes) -> List[bytes]:
162
+ frames: List[bytes] = []
163
+ offset = 0
164
+ while offset < len(stream):
165
+ ln, off = decode_uint(stream, offset)
166
+ end = off + ln
167
+ if end > len(stream):
168
+ raise GobDecodeError("frame length exceeds stream size")
169
+ frames.append(stream[off:end])
170
+ offset = end
171
+ return frames
172
+
173
+
174
+ def parse_gob_frames(stream: bytes) -> List[GobFrame]:
175
+ out: List[GobFrame] = []
176
+ for frame in split_gob_frames(stream):
177
+ type_id, off = decode_int(frame, 0)
178
+ out.append(GobFrame(type_id=abs(type_id), is_type_def=(type_id < 0), payload=frame[off:]))
179
+ return out
180
+
181
+
182
+ def maybe_is_general_ws_resp_type_def(payload: bytes) -> bool:
183
+ required = {b"ReqIdentifier", b"ErrCode", b"ErrMsg", b"MsgIncr", b"OperationID", b"Data"}
184
+ return required.issubset(set(re.findall(rb"[A-Za-z][A-Za-z0-9]+", payload)))
185
+
186
+
187
+ def extract_general_ws_resp_field_order(payload: bytes) -> Optional[List[str]]:
188
+ # Some deployments emit a gob type-def named `Resp` whose field token order
189
+ # does not match the actual encoded value order. Prefer the observed wire
190
+ # order used by current OpenIM servers and fall back to the legacy order
191
+ # during payload decode.
192
+ return list(RESP_FIELD_ORDER_OBSERVED) if maybe_is_general_ws_resp_type_def(payload) else None
193
+
194
+
195
+ def decode_general_ws_resp_payload(payload: bytes, field_order: Optional[List[str]] = None) -> Dict[str, Any]:
196
+ # payload is struct body after positive type-id.
197
+ # if field_order is not provided, use legacy order.
198
+ if not field_order:
199
+ field_order = ["ReqIdentifier", "ErrCode", "ErrMsg", "MsgIncr", "OperationID", "Data"]
200
+
201
+ field = -1
202
+ off = 0
203
+ out: Dict[str, Any] = {
204
+ "ReqIdentifier": 0,
205
+ "ErrCode": 0,
206
+ "ErrMsg": "",
207
+ "MsgIncr": "",
208
+ "OperationID": "",
209
+ "Data": b"",
210
+ }
211
+
212
+ while True:
213
+ delta, off = decode_uint(payload, off)
214
+ if delta == 0:
215
+ break
216
+ field += delta
217
+ if field < 0 or field >= len(field_order):
218
+ raise GobDecodeError(f"unknown GeneralWsResp field number: {field}")
219
+ name = field_order[field]
220
+ if name in ("ReqIdentifier", "ErrCode"):
221
+ v, off = decode_int(payload, off)
222
+ out[name] = int(v)
223
+ elif name in ("ErrMsg", "MsgIncr", "OperationID"):
224
+ v, off = _decode_string(payload, off)
225
+ out[name] = v
226
+ elif name == "Data":
227
+ v, off = _decode_bytes(payload, off)
228
+ out[name] = v
229
+ else:
230
+ raise GobDecodeError(f"unknown GeneralWsResp field name: {name}")
231
+ return out
232
+
233
+
234
+ def decode_general_ws_resp_payload_best_effort(
235
+ payload: bytes, field_order: Optional[List[str]] = None
236
+ ) -> Tuple[Dict[str, Any], List[str]]:
237
+ candidates: List[List[str]] = []
238
+ if field_order:
239
+ candidates.append(list(field_order))
240
+ for order in RESP_FIELD_ORDER_CANDIDATES:
241
+ if order not in candidates:
242
+ candidates.append(list(order))
243
+
244
+ best_error: Optional[Exception] = None
245
+ best_score = -1
246
+ best_result: Optional[Dict[str, Any]] = None
247
+ best_order: Optional[List[str]] = None
248
+
249
+ for order in candidates:
250
+ try:
251
+ decoded = decode_general_ws_resp_payload(payload, order)
252
+ except GobDecodeError as exc:
253
+ if best_error is None:
254
+ best_error = exc
255
+ continue
256
+ score = _score_general_ws_resp(decoded)
257
+ if score > best_score:
258
+ best_score = score
259
+ best_result = decoded
260
+ best_order = order
261
+
262
+ if best_result is None or best_order is None:
263
+ if best_error is not None:
264
+ raise best_error
265
+ raise GobDecodeError("unable to decode GeneralWsResp payload")
266
+ return best_result, best_order
267
+
268
+
269
+ def _score_general_ws_resp(decoded: Dict[str, Any]) -> int:
270
+ score = 0
271
+ req_identifier = decoded.get("ReqIdentifier", 0)
272
+ if isinstance(req_identifier, int) and 0 < req_identifier < 10000:
273
+ score += 5
274
+ err_code = decoded.get("ErrCode", 0)
275
+ if isinstance(err_code, int) and abs(err_code) < 1_000_000:
276
+ score += 1
277
+ msg_incr = str(decoded.get("MsgIncr", "") or "")
278
+ operation_id = str(decoded.get("OperationID", "") or "")
279
+ if msg_incr:
280
+ score += 3 if bool(re.fullmatch(r"[A-Za-z0-9_:-]+", msg_incr)) else 1
281
+ if operation_id:
282
+ score += 2 if bool(re.fullmatch(r"\d{10,}", operation_id)) else 1
283
+ data = decoded.get("Data", b"")
284
+ if isinstance(data, (bytes, bytearray)):
285
+ score += 1
286
+ err_msg = str(decoded.get("ErrMsg", "") or "")
287
+ if err_msg:
288
+ score += 1
289
+ return score
@@ -0,0 +1,47 @@
1
+ from typing import Any, Callable, Dict, List, Sequence
2
+
3
+
4
+ PostAPI = Callable[[str, Dict[str, Any]], Dict[str, Any]]
5
+
6
+
7
+ def fetch_groups_info(
8
+ *,
9
+ group_ids: Sequence[str],
10
+ post_api: PostAPI,
11
+ ) -> List[Dict[str, Any]]:
12
+ normalized_group_ids = _normalize_group_ids(group_ids)
13
+ if not normalized_group_ids:
14
+ raise ValueError("group_ids is required")
15
+
16
+ data = post_api("/group/get_groups_info", {"groupIDs": normalized_group_ids})
17
+ group_infos = data.get("groupInfos", [])
18
+ if not isinstance(group_infos, list):
19
+ return []
20
+ return [dict(group_info) for group_info in group_infos if isinstance(group_info, dict)]
21
+
22
+
23
+ def fetch_group_info(
24
+ *,
25
+ group_id: str,
26
+ post_api: PostAPI,
27
+ make_not_found_error: Callable[[str], Exception],
28
+ ) -> Dict[str, Any]:
29
+ normalized_group_id = str(group_id or "").strip()
30
+ if not normalized_group_id:
31
+ raise ValueError("group_id is required")
32
+
33
+ for group_info in fetch_groups_info(group_ids=[normalized_group_id], post_api=post_api):
34
+ if str(group_info.get("groupID", "") or "") == normalized_group_id:
35
+ return group_info
36
+ raise make_not_found_error(normalized_group_id)
37
+
38
+
39
+ def _normalize_group_ids(group_ids: Sequence[str]) -> List[str]:
40
+ normalized: List[str] = []
41
+ seen: set[str] = set()
42
+ for group_id in group_ids:
43
+ text = str(group_id or "").strip()
44
+ if text and text not in seen:
45
+ seen.add(text)
46
+ normalized.append(text)
47
+ return normalized
@@ -0,0 +1,58 @@
1
+ import gzip
2
+ import json
3
+ from io import BytesIO
4
+ import urllib.error
5
+ import urllib.request
6
+ from typing import Any, Callable, Dict
7
+
8
+
9
+ def post_json_data(
10
+ *,
11
+ api_addr: str,
12
+ route: str,
13
+ payload: Dict[str, Any],
14
+ token: str,
15
+ operation_id: str,
16
+ timeout_seconds: float,
17
+ make_http_error: Callable[[int, str], Exception],
18
+ make_sdk_error: Callable[[int, str, str], Exception],
19
+ ) -> Dict[str, Any]:
20
+ if not route.startswith("/"):
21
+ route = "/" + route
22
+ url = api_addr.rstrip("/") + route
23
+ body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
24
+ req = urllib.request.Request(url=url, method="POST", data=body)
25
+ req.add_header("Content-Type", "application/json")
26
+ req.add_header("operationID", operation_id)
27
+ req.add_header("token", token)
28
+ req.add_header("Accept-Encoding", "gzip")
29
+
30
+ try:
31
+ with urllib.request.urlopen(req, timeout=timeout_seconds) as resp:
32
+ raw = resp.read()
33
+ if resp.headers.get("Content-Encoding", "") == "gzip":
34
+ raw = gzip.decompress(raw)
35
+ decoded = raw.decode("utf-8")
36
+ except urllib.error.HTTPError as exc:
37
+ raw = exc.read()
38
+ if exc.headers.get("Content-Encoding", "") == "gzip" or raw[:2] == b"\x1f\x8b":
39
+ try:
40
+ raw = gzip.decompress(raw)
41
+ except Exception:
42
+ try:
43
+ raw = gzip.GzipFile(fileobj=BytesIO(raw)).read()
44
+ except Exception:
45
+ pass
46
+ body_text = raw.decode("utf-8", errors="ignore")
47
+ raise make_http_error(exc.code, body_text) from exc
48
+ except urllib.error.URLError as exc:
49
+ raise ConnectionError(str(exc.reason)) from exc
50
+
51
+ result = json.loads(decoded)
52
+ err_code = int(result.get("errCode", 0) or 0)
53
+ if err_code != 0:
54
+ err_msg = str(result.get("errMsg", "") or "")
55
+ err_dlt = str(result.get("errDlt", "") or "")
56
+ raise make_sdk_error(err_code, err_msg, err_dlt)
57
+ data = result.get("data", {})
58
+ return data if isinstance(data, dict) else {}