telethon-redis 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.
@@ -0,0 +1,28 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ publish:
13
+ runs-on: ubuntu-latest
14
+ environment:
15
+ name: pypi
16
+ url: https://pypi.org/p/telethon-redis
17
+ permissions:
18
+ id-token: write
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+ - uses: astral-sh/setup-uv@v5
22
+ with:
23
+ enable-cache: true
24
+ - run: uv python install 3.10
25
+ - run: uv sync --locked
26
+ - run: uv run --locked python -m unittest discover -s tests -v
27
+ - run: uv build
28
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,13 @@
1
+ build/
2
+ dist/
3
+ releases/
4
+ *.egg-info/
5
+ *.egg
6
+ __pycache__/
7
+ *.py[cod]
8
+ .installed.cfg
9
+ .idea/
10
+ *.pyc
11
+ *.pyo
12
+ *.pyd
13
+ *.log
@@ -0,0 +1 @@
1
+ 3.10
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2018 Konstantin M. (ezdev128)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,172 @@
1
+ Metadata-Version: 2.5
2
+ Name: telethon-redis
3
+ Version: 0.1.0
4
+ Summary: Redis session storage for Telethon
5
+ Author: M4hbod
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.10
9
+ Requires-Dist: redis>=8.1.0
10
+ Requires-Dist: telethon>=1.31.0
11
+ Description-Content-Type: text/markdown
12
+
13
+ # Telethon Redis session
14
+
15
+ A Redis-backed session implementation for [Telethon](https://github.com/LonamiWebs/Telethon).
16
+
17
+ Multiple accounts can share a Redis database; each account uses a distinct session name.
18
+
19
+
20
+ ## Setup
21
+
22
+ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
23
+
24
+ The minimum Telethon version is **1.31.0**. Earlier releases import `imghdr`,
25
+ which was [removed in Python 3.13](https://docs.python.org/3.13/library/imghdr.html).
26
+ Version 1.31.0 provides the required session APIs without that dependency.
27
+
28
+ ```sh
29
+ uv sync --locked
30
+ ```
31
+
32
+ This installs this checkout and its development dependencies into `.venv`.
33
+ After updating the checkout, run the same command. After deliberately changing
34
+ dependencies, regenerate `uv.lock` with `uv lock`.
35
+
36
+ To install this package from PyPI in another uv-managed service:
37
+
38
+ ```sh
39
+ uv add telethon-redis
40
+ ```
41
+
42
+ ## Usage
43
+
44
+ Provide `REDIS_URL`, `TELEGRAM_API_ID`, and `TELEGRAM_API_HASH` through your
45
+ environment or secret manager. Use a stable, unique session name for each account.
46
+
47
+ ```python
48
+ import os
49
+
50
+ import redis
51
+ from telethon import TelegramClient
52
+ from teleredis import RedisSession
53
+
54
+ connection = redis.Redis.from_url(os.environ["REDIS_URL"], decode_responses=False)
55
+ session = RedisSession("account_name", connection)
56
+ client = TelegramClient(
57
+ session,
58
+ int(os.environ["TELEGRAM_API_ID"]),
59
+ os.environ["TELEGRAM_API_HASH"],
60
+ )
61
+ client.start()
62
+ ```
63
+
64
+ Save the example as `bot.py` and run it with `uv run --locked python bot.py`.
65
+
66
+ ## Storage and startup
67
+
68
+ Under the default `telethon:client` hive:
69
+
70
+ | Key | Purpose |
71
+ | --- | --- |
72
+ | `telethon:client:<session>:active_dc` | Active data-center ID |
73
+ | `telethon:client:<session>:sessions:<dc_id>` | Connection metadata and authentication key |
74
+
75
+ Session loading uses two direct `GET` commands. Writes atomically update the
76
+ session record and active-DC pointer with `MSET`. Telethon's startup self-ID
77
+ lookups use one `MGET` per lookup for the possible user, chat, and channel entity
78
+ keys instead of scanning all entities. When IDs overlap, lookup prefers user,
79
+ then chat, then channel. Exact-ID lookups use one `GET`.
80
+
81
+ **Existing accounts must be migrated before deploying this version.** Startup
82
+ never discovers old records or repairs pointers automatically:
83
+
84
+ - A missing pointer means a new, unauthenticated session.
85
+ - A pointer whose record is missing raises an error instead of selecting another DC.
86
+ - A record whose DC disagrees with its pointer also raises an error.
87
+
88
+ Phone, username, and name lookups still use `KEYS`; they are not part of ordinary
89
+ saved-session startup. The public `list_sessions()` maintenance method uses
90
+ incremental `SCAN` but is never called while loading a session.
91
+
92
+ ## Migrate existing sessions
93
+
94
+ Run from the repository root after `uv sync --locked`.
95
+
96
+ 1. **Back up Redis and verify your restore procedure.** Stop every client writing
97
+ this session hive, including supervisors, workers, and login services. Keep
98
+ them stopped through migration and deployment. Do not mix old and new writers.
99
+
100
+ 2. Export `REDIS_URL` for the correct host and database, preferably through your
101
+ secret manager. For a local instance without authentication:
102
+
103
+ ```sh
104
+ export REDIS_URL='redis://localhost:6379/0'
105
+ ```
106
+
107
+ 3. Preview the migration. Without `--apply`, nothing is written:
108
+
109
+ ```sh
110
+ uv run --locked python scripts/migrate_active_dc.py
111
+ ```
112
+
113
+ The command traverses the database once with incremental `SCAN`, fetching only
114
+ matching session records, never entity values. It preserves a valid active
115
+ pointer or selects the sole authenticated DC, ignoring empty-auth placeholders.
116
+ Any validation or selection error prevents all writes.
117
+
118
+ 4. If an account has multiple authenticated DC records, determine its intended
119
+ active DC from your account configuration or known working deployment.
120
+ Create `active-dcs.json` with explicit choices:
121
+
122
+ ```json
123
+ {
124
+ "account_name": 4,
125
+ "another_account_name": 5
126
+ }
127
+ ```
128
+
129
+ Use the exact session names passed to `RedisSession`, including the leading
130
+ `+` for phone-number session names. Explicit choices override existing
131
+ pointers, so review the preview:
132
+
133
+ ```sh
134
+ uv run --locked python scripts/migrate_active_dc.py --dc-map active-dcs.json
135
+ ```
136
+
137
+ 5. Apply the reviewed plan:
138
+
139
+ ```sh
140
+ uv run --locked python scripts/migrate_active_dc.py --apply
141
+ # If explicit choices were required:
142
+ uv run --locked python scripts/migrate_active_dc.py --dc-map active-dcs.json --apply
143
+ ```
144
+
145
+ Only active-DC pointers are written, in one atomic `MSET`. Authentication keys,
146
+ session records, entities, and cached files are not rewritten or deleted.
147
+ **Keep the per-DC records:** the runtime still uses them.
148
+
149
+ 6. Rerun the preview to check the pointers, deploy the patched package to every
150
+ client, then start the clients. Ordinary startup performs no keyspace traversal.
151
+ If a selected record is later deleted, stop its writers and repair the pointer
152
+ explicitly with this procedure.
153
+
154
+ For a custom hive, pass `--hive-prefix` on every migration invocation.
155
+ For pickle-serialized sessions, explicitly pass `--format pickle`.
156
+ **Only unpickle trusted Redis data: pickle can execute arbitrary code.**
157
+ The default format is JSON.
158
+
159
+ ## Development
160
+
161
+ ```sh
162
+ uv run --locked python -m unittest discover -s tests -v
163
+ uv build
164
+ ```
165
+
166
+ Package metadata and dependencies live in `pyproject.toml`; `uv.lock` records the
167
+ resolved environment. The package version comes from `teleredis/__init__.py`.
168
+
169
+ ## Credits
170
+
171
+ Based on [telethon-session-redis](https://github.com/ezdev128/telethon-session-redis)
172
+ by [Konstantin M. (@ezdev128)](https://github.com/ezdev128).
@@ -0,0 +1,160 @@
1
+ # Telethon Redis session
2
+
3
+ A Redis-backed session implementation for [Telethon](https://github.com/LonamiWebs/Telethon).
4
+
5
+ Multiple accounts can share a Redis database; each account uses a distinct session name.
6
+
7
+
8
+ ## Setup
9
+
10
+ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
11
+
12
+ The minimum Telethon version is **1.31.0**. Earlier releases import `imghdr`,
13
+ which was [removed in Python 3.13](https://docs.python.org/3.13/library/imghdr.html).
14
+ Version 1.31.0 provides the required session APIs without that dependency.
15
+
16
+ ```sh
17
+ uv sync --locked
18
+ ```
19
+
20
+ This installs this checkout and its development dependencies into `.venv`.
21
+ After updating the checkout, run the same command. After deliberately changing
22
+ dependencies, regenerate `uv.lock` with `uv lock`.
23
+
24
+ To install this package from PyPI in another uv-managed service:
25
+
26
+ ```sh
27
+ uv add telethon-redis
28
+ ```
29
+
30
+ ## Usage
31
+
32
+ Provide `REDIS_URL`, `TELEGRAM_API_ID`, and `TELEGRAM_API_HASH` through your
33
+ environment or secret manager. Use a stable, unique session name for each account.
34
+
35
+ ```python
36
+ import os
37
+
38
+ import redis
39
+ from telethon import TelegramClient
40
+ from teleredis import RedisSession
41
+
42
+ connection = redis.Redis.from_url(os.environ["REDIS_URL"], decode_responses=False)
43
+ session = RedisSession("account_name", connection)
44
+ client = TelegramClient(
45
+ session,
46
+ int(os.environ["TELEGRAM_API_ID"]),
47
+ os.environ["TELEGRAM_API_HASH"],
48
+ )
49
+ client.start()
50
+ ```
51
+
52
+ Save the example as `bot.py` and run it with `uv run --locked python bot.py`.
53
+
54
+ ## Storage and startup
55
+
56
+ Under the default `telethon:client` hive:
57
+
58
+ | Key | Purpose |
59
+ | --- | --- |
60
+ | `telethon:client:<session>:active_dc` | Active data-center ID |
61
+ | `telethon:client:<session>:sessions:<dc_id>` | Connection metadata and authentication key |
62
+
63
+ Session loading uses two direct `GET` commands. Writes atomically update the
64
+ session record and active-DC pointer with `MSET`. Telethon's startup self-ID
65
+ lookups use one `MGET` per lookup for the possible user, chat, and channel entity
66
+ keys instead of scanning all entities. When IDs overlap, lookup prefers user,
67
+ then chat, then channel. Exact-ID lookups use one `GET`.
68
+
69
+ **Existing accounts must be migrated before deploying this version.** Startup
70
+ never discovers old records or repairs pointers automatically:
71
+
72
+ - A missing pointer means a new, unauthenticated session.
73
+ - A pointer whose record is missing raises an error instead of selecting another DC.
74
+ - A record whose DC disagrees with its pointer also raises an error.
75
+
76
+ Phone, username, and name lookups still use `KEYS`; they are not part of ordinary
77
+ saved-session startup. The public `list_sessions()` maintenance method uses
78
+ incremental `SCAN` but is never called while loading a session.
79
+
80
+ ## Migrate existing sessions
81
+
82
+ Run from the repository root after `uv sync --locked`.
83
+
84
+ 1. **Back up Redis and verify your restore procedure.** Stop every client writing
85
+ this session hive, including supervisors, workers, and login services. Keep
86
+ them stopped through migration and deployment. Do not mix old and new writers.
87
+
88
+ 2. Export `REDIS_URL` for the correct host and database, preferably through your
89
+ secret manager. For a local instance without authentication:
90
+
91
+ ```sh
92
+ export REDIS_URL='redis://localhost:6379/0'
93
+ ```
94
+
95
+ 3. Preview the migration. Without `--apply`, nothing is written:
96
+
97
+ ```sh
98
+ uv run --locked python scripts/migrate_active_dc.py
99
+ ```
100
+
101
+ The command traverses the database once with incremental `SCAN`, fetching only
102
+ matching session records, never entity values. It preserves a valid active
103
+ pointer or selects the sole authenticated DC, ignoring empty-auth placeholders.
104
+ Any validation or selection error prevents all writes.
105
+
106
+ 4. If an account has multiple authenticated DC records, determine its intended
107
+ active DC from your account configuration or known working deployment.
108
+ Create `active-dcs.json` with explicit choices:
109
+
110
+ ```json
111
+ {
112
+ "account_name": 4,
113
+ "another_account_name": 5
114
+ }
115
+ ```
116
+
117
+ Use the exact session names passed to `RedisSession`, including the leading
118
+ `+` for phone-number session names. Explicit choices override existing
119
+ pointers, so review the preview:
120
+
121
+ ```sh
122
+ uv run --locked python scripts/migrate_active_dc.py --dc-map active-dcs.json
123
+ ```
124
+
125
+ 5. Apply the reviewed plan:
126
+
127
+ ```sh
128
+ uv run --locked python scripts/migrate_active_dc.py --apply
129
+ # If explicit choices were required:
130
+ uv run --locked python scripts/migrate_active_dc.py --dc-map active-dcs.json --apply
131
+ ```
132
+
133
+ Only active-DC pointers are written, in one atomic `MSET`. Authentication keys,
134
+ session records, entities, and cached files are not rewritten or deleted.
135
+ **Keep the per-DC records:** the runtime still uses them.
136
+
137
+ 6. Rerun the preview to check the pointers, deploy the patched package to every
138
+ client, then start the clients. Ordinary startup performs no keyspace traversal.
139
+ If a selected record is later deleted, stop its writers and repair the pointer
140
+ explicitly with this procedure.
141
+
142
+ For a custom hive, pass `--hive-prefix` on every migration invocation.
143
+ For pickle-serialized sessions, explicitly pass `--format pickle`.
144
+ **Only unpickle trusted Redis data: pickle can execute arbitrary code.**
145
+ The default format is JSON.
146
+
147
+ ## Development
148
+
149
+ ```sh
150
+ uv run --locked python -m unittest discover -s tests -v
151
+ uv build
152
+ ```
153
+
154
+ Package metadata and dependencies live in `pyproject.toml`; `uv.lock` records the
155
+ resolved environment. The package version comes from `teleredis/__init__.py`.
156
+
157
+ ## Credits
158
+
159
+ Based on [telethon-session-redis](https://github.com/ezdev128/telethon-session-redis)
160
+ by [Konstantin M. (@ezdev128)](https://github.com/ezdev128).
@@ -0,0 +1,29 @@
1
+ [project]
2
+ name = "telethon-redis"
3
+ dynamic = ["version"]
4
+ description = "Redis session storage for Telethon"
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = "MIT"
8
+ authors = [
9
+ { name = "M4hbod" },
10
+ ]
11
+ dependencies = [
12
+ "redis>=8.1.0",
13
+ "telethon>=1.31.0",
14
+ ]
15
+
16
+ [dependency-groups]
17
+ dev = [
18
+ "fakeredis>=2.0",
19
+ ]
20
+
21
+ [build-system]
22
+ requires = ["hatchling>=1.27,<2"]
23
+ build-backend = "hatchling.build"
24
+
25
+ [tool.hatch.version]
26
+ path = "teleredis/__init__.py"
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["teleredis"]
@@ -0,0 +1,247 @@
1
+ #!/usr/bin/env python3
2
+ """Explicitly migrate legacy session records to active-DC pointers.
3
+
4
+ Pickle records can execute code while being loaded. Use ``--format pickle`` only
5
+ with trusted Redis data. Stop all application writers before applying a plan.
6
+ """
7
+
8
+ import argparse
9
+ import base64
10
+ import binascii
11
+ import json
12
+ import os
13
+ import pickle
14
+ import re
15
+ import sys
16
+
17
+ import redis
18
+
19
+
20
+ def _text(value):
21
+ if isinstance(value, bytes):
22
+ return value.decode("utf-8")
23
+ if isinstance(value, str):
24
+ return value
25
+ raise ValueError("expected text")
26
+
27
+
28
+ def _redis_pattern_literal(text):
29
+ """Escape Redis glob metacharacters in a literal prefix."""
30
+ return re.sub(r"([\\*?\[\]])", r"\\\1", text)
31
+
32
+
33
+ def _decode_record(raw, pack_format):
34
+ try:
35
+ if pack_format == "json":
36
+ if isinstance(raw, bytes):
37
+ raw = raw.decode("utf-8")
38
+ return json.loads(raw)
39
+ return pickle.loads(raw)
40
+ except Exception:
41
+ # Decoder exceptions may quote the raw value, which can contain auth data.
42
+ raise ValueError(f"record is not valid {pack_format}")
43
+
44
+
45
+ def _positive_int(value):
46
+ if isinstance(value, bool):
47
+ return None
48
+ if isinstance(value, int):
49
+ return value if value > 0 else None
50
+ if isinstance(value, bytes):
51
+ try:
52
+ value = value.decode("ascii")
53
+ except UnicodeDecodeError:
54
+ return None
55
+ if isinstance(value, str) and value.isdecimal():
56
+ try:
57
+ number = int(value)
58
+ except ValueError:
59
+ return None
60
+ return number if number > 0 else None
61
+ return None
62
+
63
+
64
+ def _validate_record(raw, key_dc, pack_format):
65
+ record = _decode_record(raw, pack_format)
66
+ if not isinstance(record, dict):
67
+ raise ValueError("record must be an object")
68
+ dc_value = record.get("dc_id")
69
+ dc_id = dc_value if isinstance(dc_value, int) and not isinstance(dc_value, bool) else None
70
+ if dc_id is None or dc_id <= 0 or dc_id != key_dc:
71
+ raise ValueError("dc_id does not match the session key")
72
+ address = record.get("server_address")
73
+ if not isinstance(address, str) or not address.strip():
74
+ raise ValueError("server_address must be nonempty")
75
+ port = record.get("port")
76
+ if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
77
+ raise ValueError("port must be an integer from 1 to 65535")
78
+ auth_encoded = record.get("auth_key")
79
+ if not isinstance(auth_encoded, str):
80
+ raise ValueError("auth_key must be base64 text")
81
+ try:
82
+ auth_key = base64.b64decode(auth_encoded, validate=True)
83
+ except (binascii.Error, ValueError):
84
+ raise ValueError("auth_key is not valid base64")
85
+ if auth_key and len(auth_key) != 256:
86
+ raise ValueError("auth_key must decode to 256 bytes (or be empty)")
87
+ return bool(auth_key)
88
+
89
+
90
+ def build_plan(connection, hive_prefix="telethon:client", pack_format="json", dc_map=None):
91
+ """Return (pointer-key -> DC plan, errors) without writing to Redis."""
92
+ plan = {}
93
+ errors = []
94
+ if pack_format not in ("json", "pickle"):
95
+ return plan, ["format must be 'json' or 'pickle'"]
96
+ try:
97
+ prefix = _text(hive_prefix)
98
+ except (UnicodeDecodeError, ValueError):
99
+ return plan, ["hive prefix must be text"]
100
+ if not prefix:
101
+ return plan, ["hive prefix must not be empty"]
102
+ if dc_map is None:
103
+ dc_map = {}
104
+ if not hasattr(dc_map, "items"):
105
+ return plan, ["DC map must be an object mapping session names to positive integer DCs"]
106
+
107
+ mappings = {}
108
+ for account, value in dc_map.items():
109
+ if not isinstance(account, str) or not account:
110
+ errors.append("DC map session names must be nonempty strings")
111
+ continue
112
+ target = value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
113
+ if target is None:
114
+ errors.append(f"DC map target for {account!r} must be a positive integer")
115
+ else:
116
+ mappings[account] = target
117
+
118
+ # Scan only session keys; escaping prevents prefix glob syntax from widening the match.
119
+ pattern = _redis_pattern_literal(prefix) + ":*:sessions:*"
120
+ matcher = re.compile(r"^" + re.escape(prefix) + r":(.*):sessions:([^:]+)$")
121
+ records = {}
122
+ key_type = None
123
+ try:
124
+ cursor = 0
125
+ while True:
126
+ cursor, keys = connection.scan(cursor=cursor, match=pattern, count=1000)
127
+ for key in keys:
128
+ key_type = type(key)
129
+ try:
130
+ key_text = _text(key)
131
+ match = matcher.match(key_text)
132
+ if not match:
133
+ continue
134
+ account, dc_text = match.groups()
135
+ dc_id = _positive_int(dc_text)
136
+ if dc_id is None or dc_text != str(dc_id):
137
+ errors.append(f"Malformed session key {key_text!r}: DC suffix must be a canonical positive integer")
138
+ continue
139
+ raw = connection.get(key)
140
+ if raw is None:
141
+ errors.append(f"Session record {key_text!r} disappeared during planning")
142
+ continue
143
+ try:
144
+ authenticated = _validate_record(raw, dc_id, pack_format)
145
+ except ValueError as exc:
146
+ # Avoid including record contents or exception payloads in diagnostics.
147
+ errors.append(f"Malformed session record {key_text!r}: {str(exc) or 'invalid data'}")
148
+ continue
149
+ records.setdefault(account, {})[dc_id] = authenticated
150
+ except (UnicodeDecodeError, ValueError) as exc:
151
+ errors.append(f"Could not parse a matching session key: {str(exc)}")
152
+ if not cursor:
153
+ break
154
+ except redis.RedisError:
155
+ return {}, errors + ["Redis error while scanning session keys"]
156
+
157
+ for account in mappings:
158
+ if account not in records:
159
+ errors.append(f"DC map names unknown session account {account!r}")
160
+
161
+ pointer_type = key_type or bytes
162
+ for account, candidates in records.items():
163
+ pointer_text = f"{prefix}:{account}:active_dc"
164
+ pointer_key = pointer_text.encode("utf-8") if pointer_type is bytes else pointer_text
165
+ try:
166
+ current = connection.get(pointer_key)
167
+ except redis.RedisError:
168
+ errors.append(f"Redis error while reading active-DC pointer for {account!r}")
169
+ continue
170
+ current_dc = _positive_int(current) if current is not None else None
171
+ authenticated = {dc: valid for dc, valid in candidates.items() if valid}
172
+ if account in mappings:
173
+ selected = mappings[account]
174
+ if not authenticated.get(selected, False):
175
+ errors.append(f"DC map target {selected} for {account!r} is not an authenticated session record")
176
+ continue
177
+ elif current_dc is not None and authenticated.get(current_dc, False):
178
+ selected = current_dc
179
+ elif len(authenticated) == 1:
180
+ selected = next(iter(authenticated))
181
+ elif len(authenticated) > 1:
182
+ errors.append(f"Session account {account!r} has multiple authenticated DCs; provide an explicit DC map entry")
183
+ continue
184
+ else:
185
+ # Empty-auth placeholders are not migration candidates.
186
+ continue
187
+ plan[pointer_key] = selected
188
+
189
+ return ({} if errors else plan), errors
190
+
191
+
192
+ def _load_dc_map(filename):
193
+ with open(filename, "r", encoding="utf-8") as source:
194
+ value = json.load(source)
195
+ if not isinstance(value, dict):
196
+ raise ValueError("DC map JSON must be an object")
197
+ return value
198
+
199
+
200
+ def main(argv=None):
201
+ parser = argparse.ArgumentParser(
202
+ description="Plan or explicitly migrate legacy active-DC pointers. Stop ALL Redis session writers before applying.")
203
+ parser.add_argument("--apply", action="store_true", help="write the complete plan using one atomic MSET (default: preview without writes)")
204
+ parser.add_argument("--hive-prefix", default="telethon:client", help="literal Redis hive prefix")
205
+ parser.add_argument("--format", choices=("json", "pickle"), default="json", help="session record format (pickle loads trusted data only)")
206
+ parser.add_argument("--dc-map", metavar="FILE", help="JSON object mapping session names to positive DC IDs")
207
+ args = parser.parse_args(argv)
208
+
209
+ redis_url = os.environ.get("REDIS_URL")
210
+ if not redis_url:
211
+ print("error: REDIS_URL environment variable is required", file=sys.stderr)
212
+ return 2
213
+ if args.format == "pickle":
214
+ print("Warning: pickle can execute code; use trusted Redis data only.", file=sys.stderr)
215
+ try:
216
+ dc_map = _load_dc_map(args.dc_map) if args.dc_map else None
217
+ except (OSError, ValueError):
218
+ print("error: could not read the DC map", file=sys.stderr)
219
+ return 2
220
+ try:
221
+ connection = redis.Redis.from_url(redis_url)
222
+ plan, errors = build_plan(connection, args.hive_prefix, args.format, dc_map)
223
+ except (ValueError, redis.RedisError):
224
+ print("error: invalid REDIS_URL or Redis connection failure", file=sys.stderr)
225
+ return 2
226
+
227
+ for key, dc_id in plan.items():
228
+ display_key = _text(key)
229
+ print(f"{display_key} -> {dc_id}")
230
+ for error in errors:
231
+ print(f"error: {error}", file=sys.stderr)
232
+ if errors:
233
+ return 1
234
+ if args.apply and plan:
235
+ try:
236
+ connection.mset(plan)
237
+ except redis.RedisError:
238
+ print("error: Redis failed to apply the active-DC plan", file=sys.stderr)
239
+ return 2
240
+ print(f"Applied {len(plan)} active-DC pointer(s).")
241
+ elif not args.apply:
242
+ print(f"Dry run: {len(plan)} active-DC pointer(s) selected; no writes made.")
243
+ return 0
244
+
245
+
246
+ if __name__ == "__main__":
247
+ sys.exit(main())
@@ -0,0 +1,8 @@
1
+
2
+ from .teleredis import RedisSession, PackFunction, UnpackFunction
3
+
4
+ __version__ = "0.1.0"
5
+ __all__ = [
6
+ "RedisSession",
7
+ ]
8
+