sub2api 0.2.0__tar.gz → 0.3.1__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.
- {sub2api-0.2.0 → sub2api-0.3.1}/PKG-INFO +32 -5
- {sub2api-0.2.0 → sub2api-0.3.1}/README.md +31 -4
- {sub2api-0.2.0 → sub2api-0.3.1}/pyproject.toml +1 -1
- {sub2api-0.2.0 → sub2api-0.3.1}/src/sub2api/__init__.py +9 -1
- {sub2api-0.2.0 → sub2api-0.3.1}/src/sub2api/_client.py +226 -85
- {sub2api-0.2.0 → sub2api-0.3.1}/src/sub2api/_exceptions.py +12 -0
- {sub2api-0.2.0 → sub2api-0.3.1}/src/sub2api/_models.py +2 -2
- sub2api-0.3.1/src/sub2api/_token_store.py +21 -0
- sub2api-0.3.1/tests/test_client.py +677 -0
- sub2api-0.2.0/.gitignore +0 -11
- sub2api-0.2.0/tests/test_client.py +0 -308
- {sub2api-0.2.0 → sub2api-0.3.1}/LICENSE +0 -0
- {sub2api-0.2.0 → sub2api-0.3.1}/src/sub2api/_resources.py +0 -0
- {sub2api-0.2.0 → sub2api-0.3.1}/src/sub2api/py.typed +0 -0
- {sub2api-0.2.0 → sub2api-0.3.1}/tests/test_resources.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: sub2api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: Python client for the user-facing API of Sub2API instances
|
|
5
5
|
Author: Eight Labs
|
|
6
6
|
License-Expression: MIT
|
|
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
|
|
|
29
29
|
|
|
30
30
|
# sub2api
|
|
31
31
|
|
|
32
|
-
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's
|
|
32
|
+
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
|
|
33
33
|
|
|
34
34
|
The library targets operations present on standard Sub2API deployments: account balance, optional payment deposits, payment orders, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
|
|
35
35
|
|
|
@@ -43,7 +43,7 @@ Python 3.10 or newer is required.
|
|
|
43
43
|
|
|
44
44
|
## Authenticate with an existing session
|
|
45
45
|
|
|
46
|
-
The
|
|
46
|
+
The client authenticates with a dashboard access token. If your integration owns the session and its renewal, you can also supply its refresh token.
|
|
47
47
|
|
|
48
48
|
```python
|
|
49
49
|
import os
|
|
@@ -60,9 +60,9 @@ print(client.me().email)
|
|
|
60
60
|
print(client.balance().balance)
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
Pass either the instance origin or its full `/api/v1` URL.
|
|
63
|
+
Pass either the instance origin or its full `/api/v1` URL. By default, the client keeps its tokens in memory and attempts renewal after an authenticated `401` if it has a refresh token. Supplying `expires_at` as a Unix timestamp also enables proactive renewal within 30 seconds of expiry.
|
|
64
64
|
|
|
65
|
-
The default browser fingerprint is Chrome.
|
|
65
|
+
The default browser fingerprint is Chrome. The selected `curl_cffi` browser profile also supplies the default `User-Agent`. You can choose another profile, set a custom `User-Agent`, or configure proxies with your own `curl_cffi.requests.Session`.
|
|
66
66
|
|
|
67
67
|
```python
|
|
68
68
|
from curl_cffi import requests
|
|
@@ -71,6 +71,33 @@ session = requests.Session(impersonate="safari")
|
|
|
71
71
|
client = Sub2API("https://sub2api.example.com", session=session)
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
+
### Use a browser-managed session
|
|
75
|
+
|
|
76
|
+
If the dashboard owns renewal, pass its access token with `externally_managed=True`. The client surfaces the original `401`. When the dashboard supplies a new token, call `set_access_token()` on the existing client. You can pass `expires_at` with either call to retain the dashboard's expiry timestamp.
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
client = Sub2API(
|
|
80
|
+
"https://sub2api.example.com",
|
|
81
|
+
access_token=dashboard_access_token,
|
|
82
|
+
externally_managed=True,
|
|
83
|
+
)
|
|
84
|
+
client.set_access_token(updated_dashboard_access_token)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Persist and share a library-managed session
|
|
88
|
+
|
|
89
|
+
Pass a `token_store` that implements `TokenStore`. The client uses the stored `SessionTokens` when present and can initialize an empty store from the constructor credentials. Keep one store per user session and instance. Each write must persist `access_token`, `refresh_token`, `expires_at`, and `token_type` together.
|
|
90
|
+
|
|
91
|
+
- `load()` returns the current snapshot, or `None` for an uninitialized store.
|
|
92
|
+
- `save(tokens)` atomically replaces the snapshot after a successful login, including 2FA.
|
|
93
|
+
- `compare_and_set(expected, tokens)` atomically replaces the snapshot only if it matches `expected`. Return `False` when another writer has changed it. An empty `SessionTokens()` snapshot represents a cleared session.
|
|
94
|
+
|
|
95
|
+
When multiple clients share the session, pass the same `refresh_lock` to each client along with the shared store. A `threading.Lock()` works for threads in one process. Workers in separate processes need a lock that coordinates across those processes and supports `with`. Clients reload the stored pair under that lock and save a rotation before releasing it or retrying the original request.
|
|
96
|
+
|
|
97
|
+
If the rotation write raises, the client surfaces the store exception and keeps the new pair in `client.tokens`. Call `client.save_tokens()` to retry the conditional write without another refresh request. A newer login in the store takes precedence over a pending rotation.
|
|
98
|
+
|
|
99
|
+
Rate limits, transport errors, and server errors during renewal leave credentials intact. HTTP errors expose `retry_after` in seconds when the server supplies a valid `Retry-After` header. After a transport failure the client checks the store for a replacement pair, and surfaces `TransportError` if it finds none. `SessionExpiredError`, `SessionRevokedError`, and `SessionBindingError` are subclasses of `AuthenticationError` that carry the server's reason or code.
|
|
100
|
+
|
|
74
101
|
## Log in with email and password
|
|
75
102
|
|
|
76
103
|
```python
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# sub2api
|
|
2
2
|
|
|
3
|
-
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's
|
|
3
|
+
`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
|
|
4
4
|
|
|
5
5
|
The library targets operations present on standard Sub2API deployments: account balance, optional payment deposits, payment orders, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
|
|
6
6
|
|
|
@@ -14,7 +14,7 @@ Python 3.10 or newer is required.
|
|
|
14
14
|
|
|
15
15
|
## Authenticate with an existing session
|
|
16
16
|
|
|
17
|
-
The
|
|
17
|
+
The client authenticates with a dashboard access token. If your integration owns the session and its renewal, you can also supply its refresh token.
|
|
18
18
|
|
|
19
19
|
```python
|
|
20
20
|
import os
|
|
@@ -31,9 +31,9 @@ print(client.me().email)
|
|
|
31
31
|
print(client.balance().balance)
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
Pass either the instance origin or its full `/api/v1` URL.
|
|
34
|
+
Pass either the instance origin or its full `/api/v1` URL. By default, the client keeps its tokens in memory and attempts renewal after an authenticated `401` if it has a refresh token. Supplying `expires_at` as a Unix timestamp also enables proactive renewal within 30 seconds of expiry.
|
|
35
35
|
|
|
36
|
-
The default browser fingerprint is Chrome.
|
|
36
|
+
The default browser fingerprint is Chrome. The selected `curl_cffi` browser profile also supplies the default `User-Agent`. You can choose another profile, set a custom `User-Agent`, or configure proxies with your own `curl_cffi.requests.Session`.
|
|
37
37
|
|
|
38
38
|
```python
|
|
39
39
|
from curl_cffi import requests
|
|
@@ -42,6 +42,33 @@ session = requests.Session(impersonate="safari")
|
|
|
42
42
|
client = Sub2API("https://sub2api.example.com", session=session)
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
+
### Use a browser-managed session
|
|
46
|
+
|
|
47
|
+
If the dashboard owns renewal, pass its access token with `externally_managed=True`. The client surfaces the original `401`. When the dashboard supplies a new token, call `set_access_token()` on the existing client. You can pass `expires_at` with either call to retain the dashboard's expiry timestamp.
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
client = Sub2API(
|
|
51
|
+
"https://sub2api.example.com",
|
|
52
|
+
access_token=dashboard_access_token,
|
|
53
|
+
externally_managed=True,
|
|
54
|
+
)
|
|
55
|
+
client.set_access_token(updated_dashboard_access_token)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Persist and share a library-managed session
|
|
59
|
+
|
|
60
|
+
Pass a `token_store` that implements `TokenStore`. The client uses the stored `SessionTokens` when present and can initialize an empty store from the constructor credentials. Keep one store per user session and instance. Each write must persist `access_token`, `refresh_token`, `expires_at`, and `token_type` together.
|
|
61
|
+
|
|
62
|
+
- `load()` returns the current snapshot, or `None` for an uninitialized store.
|
|
63
|
+
- `save(tokens)` atomically replaces the snapshot after a successful login, including 2FA.
|
|
64
|
+
- `compare_and_set(expected, tokens)` atomically replaces the snapshot only if it matches `expected`. Return `False` when another writer has changed it. An empty `SessionTokens()` snapshot represents a cleared session.
|
|
65
|
+
|
|
66
|
+
When multiple clients share the session, pass the same `refresh_lock` to each client along with the shared store. A `threading.Lock()` works for threads in one process. Workers in separate processes need a lock that coordinates across those processes and supports `with`. Clients reload the stored pair under that lock and save a rotation before releasing it or retrying the original request.
|
|
67
|
+
|
|
68
|
+
If the rotation write raises, the client surfaces the store exception and keeps the new pair in `client.tokens`. Call `client.save_tokens()` to retry the conditional write without another refresh request. A newer login in the store takes precedence over a pending rotation.
|
|
69
|
+
|
|
70
|
+
Rate limits, transport errors, and server errors during renewal leave credentials intact. HTTP errors expose `retry_after` in seconds when the server supplies a valid `Retry-After` header. After a transport failure the client checks the store for a replacement pair, and surfaces `TransportError` if it finds none. `SessionExpiredError`, `SessionRevokedError`, and `SessionBindingError` are subclasses of `AuthenticationError` that carry the server's reason or code.
|
|
71
|
+
|
|
45
72
|
## Log in with email and password
|
|
46
73
|
|
|
47
74
|
```python
|
|
@@ -8,6 +8,9 @@ from ._exceptions import (
|
|
|
8
8
|
PermissionDeniedError,
|
|
9
9
|
ProtocolError,
|
|
10
10
|
RateLimitError,
|
|
11
|
+
SessionBindingError,
|
|
12
|
+
SessionExpiredError,
|
|
13
|
+
SessionRevokedError,
|
|
11
14
|
Sub2APIError,
|
|
12
15
|
TransportError,
|
|
13
16
|
TwoFactorRequired,
|
|
@@ -35,6 +38,7 @@ from ._models import (
|
|
|
35
38
|
UsageRecord,
|
|
36
39
|
User,
|
|
37
40
|
)
|
|
41
|
+
from ._token_store import TokenStore
|
|
38
42
|
|
|
39
43
|
__all__ = [
|
|
40
44
|
"APIError",
|
|
@@ -60,11 +64,15 @@ __all__ = [
|
|
|
60
64
|
"RateLimitError",
|
|
61
65
|
"Redemption",
|
|
62
66
|
"Resource",
|
|
67
|
+
"SessionBindingError",
|
|
68
|
+
"SessionExpiredError",
|
|
69
|
+
"SessionRevokedError",
|
|
63
70
|
"SessionTokens",
|
|
64
71
|
"Sub2API",
|
|
65
72
|
"Sub2APIError",
|
|
66
73
|
"Subscription",
|
|
67
74
|
"SubscriptionPlan",
|
|
75
|
+
"TokenStore",
|
|
68
76
|
"TransportError",
|
|
69
77
|
"TwoFactorRequired",
|
|
70
78
|
"UsageRecord",
|
|
@@ -72,4 +80,4 @@ __all__ = [
|
|
|
72
80
|
"ValidationError",
|
|
73
81
|
]
|
|
74
82
|
|
|
75
|
-
__version__ = "0.
|
|
83
|
+
__version__ = "0.3.1"
|
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
|
+
import math
|
|
3
4
|
import threading
|
|
4
5
|
import time
|
|
5
6
|
from collections.abc import Mapping
|
|
6
|
-
from
|
|
7
|
+
from contextlib import AbstractContextManager
|
|
8
|
+
from datetime import date, datetime, timezone
|
|
9
|
+
from email.utils import parsedate_to_datetime
|
|
7
10
|
from typing import Any, cast
|
|
8
11
|
from urllib.parse import unquote, urlsplit, urlunsplit
|
|
9
12
|
|
|
@@ -18,6 +21,9 @@ from ._exceptions import (
|
|
|
18
21
|
PermissionDeniedError,
|
|
19
22
|
ProtocolError,
|
|
20
23
|
RateLimitError,
|
|
24
|
+
SessionBindingError,
|
|
25
|
+
SessionExpiredError,
|
|
26
|
+
SessionRevokedError,
|
|
21
27
|
TransportError,
|
|
22
28
|
TwoFactorRequired,
|
|
23
29
|
ValidationError,
|
|
@@ -33,6 +39,7 @@ from ._resources import (
|
|
|
33
39
|
SubscriptionsResource,
|
|
34
40
|
UsageResource,
|
|
35
41
|
)
|
|
42
|
+
from ._token_store import TokenStore
|
|
36
43
|
|
|
37
44
|
_ERROR_TYPES: dict[int, type[APIError]] = {
|
|
38
45
|
400: ValidationError,
|
|
@@ -43,6 +50,18 @@ _ERROR_TYPES: dict[int, type[APIError]] = {
|
|
|
43
50
|
422: ValidationError,
|
|
44
51
|
429: RateLimitError,
|
|
45
52
|
}
|
|
53
|
+
_SESSION_ERROR_TYPES: dict[str, type[AuthenticationError]] = {
|
|
54
|
+
"ACCESS_TOKEN_EXPIRED": SessionExpiredError,
|
|
55
|
+
"REFRESH_TOKEN_EXPIRED": SessionExpiredError,
|
|
56
|
+
"TOKEN_EXPIRED": SessionExpiredError,
|
|
57
|
+
"REFRESH_TOKEN_REVOKED": SessionRevokedError,
|
|
58
|
+
"SESSION_REVOKED": SessionRevokedError,
|
|
59
|
+
"TOKEN_REVOKED": SessionRevokedError,
|
|
60
|
+
"SESSION_BINDING_MISMATCH": SessionBindingError,
|
|
61
|
+
}
|
|
62
|
+
_REFRESH_REJECTION_REASONS = frozenset(
|
|
63
|
+
{"INVALID_TOKEN", "REFRESH_TOKEN_INVALID", "REFRESH_TOKEN_REUSED", "USER_NOT_ACTIVE"}
|
|
64
|
+
)
|
|
46
65
|
_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
|
|
47
66
|
|
|
48
67
|
|
|
@@ -114,9 +133,24 @@ def _retry_after(response: Any) -> float | None:
|
|
|
114
133
|
if value is None:
|
|
115
134
|
return None
|
|
116
135
|
try:
|
|
117
|
-
|
|
136
|
+
delay = float(value)
|
|
118
137
|
except ValueError:
|
|
119
|
-
|
|
138
|
+
try:
|
|
139
|
+
retry_at = parsedate_to_datetime(value)
|
|
140
|
+
except (ValueError, OverflowError):
|
|
141
|
+
return None
|
|
142
|
+
if retry_at.tzinfo is None:
|
|
143
|
+
retry_at = retry_at.replace(tzinfo=timezone.utc)
|
|
144
|
+
delay = (retry_at - datetime.now(timezone.utc)).total_seconds()
|
|
145
|
+
return max(0.0, delay) if math.isfinite(delay) else None
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _refresh_rejected(error: APIError) -> bool:
|
|
149
|
+
return isinstance(error, AuthenticationError) or (
|
|
150
|
+
400 <= error.status_code < 500
|
|
151
|
+
and error.status_code != 429
|
|
152
|
+
and (error.reason in _REFRESH_REJECTION_REASONS or error.code in _REFRESH_REJECTION_REASONS)
|
|
153
|
+
)
|
|
120
154
|
|
|
121
155
|
|
|
122
156
|
class Sub2API:
|
|
@@ -135,12 +169,30 @@ class Sub2API:
|
|
|
135
169
|
allow_insecure: bool = False,
|
|
136
170
|
impersonate: str | None = "chrome",
|
|
137
171
|
session: Any | None = None,
|
|
172
|
+
externally_managed: bool = False,
|
|
173
|
+
token_store: TokenStore | None = None,
|
|
174
|
+
refresh_lock: AbstractContextManager[Any] | None = None,
|
|
138
175
|
) -> None:
|
|
139
176
|
self.base_url = _api_base_url(base_url, allow_insecure)
|
|
140
177
|
self.timezone = timezone
|
|
141
178
|
self.language = language
|
|
142
|
-
|
|
143
|
-
|
|
179
|
+
if externally_managed and token_store is not None:
|
|
180
|
+
raise ConfigurationError("token_store is only available for library-managed sessions")
|
|
181
|
+
self._externally_managed = externally_managed
|
|
182
|
+
self._token_store = token_store
|
|
183
|
+
self._tokens = SessionTokens(
|
|
184
|
+
access_token, None if externally_managed else refresh_token, expires_at
|
|
185
|
+
)
|
|
186
|
+
if token_store is not None:
|
|
187
|
+
stored = token_store.load()
|
|
188
|
+
if stored is None and (access_token or refresh_token):
|
|
189
|
+
if not token_store.compare_and_set(None, self._tokens):
|
|
190
|
+
self._tokens = token_store.load() or SessionTokens()
|
|
191
|
+
elif stored is not None:
|
|
192
|
+
self._tokens = stored
|
|
193
|
+
self._refresh_lock = threading.Lock() if refresh_lock is None else refresh_lock
|
|
194
|
+
self._auth_lock = threading.Lock()
|
|
195
|
+
self._pending_save: SessionTokens | None = None
|
|
144
196
|
self._pending_2fa_token: str | None = None
|
|
145
197
|
self.timeout = timeout
|
|
146
198
|
self.impersonate = impersonate
|
|
@@ -170,6 +222,15 @@ class Sub2API:
|
|
|
170
222
|
def is_authenticated(self) -> bool:
|
|
171
223
|
return self._tokens.authenticated
|
|
172
224
|
|
|
225
|
+
def set_access_token(self, access_token: str, *, expires_at: float | None = None) -> None:
|
|
226
|
+
"""Replace the access token for an externally managed session."""
|
|
227
|
+
if not self._externally_managed:
|
|
228
|
+
raise ConfigurationError("set_access_token requires externally_managed=True")
|
|
229
|
+
if not isinstance(access_token, str) or not access_token.strip():
|
|
230
|
+
raise ValueError("access_token must be a non-empty string")
|
|
231
|
+
with self._auth_lock:
|
|
232
|
+
self._tokens = SessionTokens(access_token=access_token, expires_at=expires_at)
|
|
233
|
+
|
|
173
234
|
def login(
|
|
174
235
|
self,
|
|
175
236
|
email: str,
|
|
@@ -226,53 +287,45 @@ class Sub2API:
|
|
|
226
287
|
return user
|
|
227
288
|
|
|
228
289
|
def refresh(self) -> SessionTokens:
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
)
|
|
245
|
-
auth = self._auth_mapping(data, "token refresh")
|
|
246
|
-
access_token = auth.get("access_token")
|
|
247
|
-
rotated_token = auth.get("refresh_token")
|
|
248
|
-
if not isinstance(access_token, str) or not access_token:
|
|
249
|
-
raise ProtocolError("token refresh did not return an access token")
|
|
250
|
-
if not isinstance(rotated_token, str) or not rotated_token:
|
|
251
|
-
raise ProtocolError("token refresh did not return a refresh token")
|
|
252
|
-
self._tokens = self._tokens_from_auth(auth)
|
|
253
|
-
return self._tokens
|
|
254
|
-
except APIError as error:
|
|
255
|
-
if 400 <= error.status_code < 500:
|
|
256
|
-
self.clear_auth()
|
|
257
|
-
raise
|
|
290
|
+
"""Renew the session or adopt a pair another worker has already saved."""
|
|
291
|
+
if self._externally_managed:
|
|
292
|
+
raise ConfigurationError("session renewal is externally managed")
|
|
293
|
+
tokens = self._renew(self._tokens)
|
|
294
|
+
if tokens is None:
|
|
295
|
+
raise AuthenticationError(
|
|
296
|
+
"No refresh token is available", status_code=401, code="NO_REFRESH_TOKEN"
|
|
297
|
+
)
|
|
298
|
+
return tokens
|
|
299
|
+
|
|
300
|
+
def save_tokens(self) -> SessionTokens:
|
|
301
|
+
"""Retry a pending rotation save and return the latest session snapshot."""
|
|
302
|
+
with self._refresh_lock, self._auth_lock:
|
|
303
|
+
self._save_rotation()
|
|
304
|
+
return self._tokens
|
|
258
305
|
|
|
259
306
|
def logout(self) -> None:
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
307
|
+
with self._refresh_lock:
|
|
308
|
+
with self._auth_lock:
|
|
309
|
+
if self._tokens.access_token or self._tokens.refresh_token:
|
|
310
|
+
self._reload_tokens()
|
|
311
|
+
tokens = self._tokens
|
|
312
|
+
try:
|
|
313
|
+
if tokens.refresh_token:
|
|
314
|
+
self._request(
|
|
315
|
+
"POST",
|
|
316
|
+
"auth/logout",
|
|
317
|
+
json={"refresh_token": tokens.refresh_token},
|
|
318
|
+
authenticated=False,
|
|
319
|
+
allow_refresh=False,
|
|
320
|
+
)
|
|
321
|
+
finally:
|
|
322
|
+
with self._auth_lock:
|
|
323
|
+
if self._tokens is tokens:
|
|
324
|
+
self._clear_tokens()
|
|
272
325
|
|
|
273
326
|
def clear_auth(self) -> None:
|
|
274
|
-
self.
|
|
275
|
-
|
|
327
|
+
with self._auth_lock:
|
|
328
|
+
self._clear_tokens()
|
|
276
329
|
|
|
277
330
|
def me(self) -> User:
|
|
278
331
|
return self.account.profile()
|
|
@@ -354,32 +407,41 @@ class Sub2API:
|
|
|
354
407
|
allow_refresh: bool,
|
|
355
408
|
) -> Any:
|
|
356
409
|
normalized_method = method.upper()
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
410
|
+
can_refresh = authenticated and allow_refresh and not self._externally_managed
|
|
411
|
+
tokens = self._tokens if authenticated else None
|
|
412
|
+
if can_refresh and tokens is not None:
|
|
413
|
+
if tokens.needs_refresh() or self._pending_save is not None:
|
|
414
|
+
self._renew(tokens, only_if_expiring=True)
|
|
415
|
+
tokens = self._tokens
|
|
360
416
|
response = self._send(
|
|
361
417
|
normalized_method,
|
|
362
418
|
path,
|
|
363
419
|
params=params,
|
|
364
420
|
json=json,
|
|
365
421
|
headers=headers,
|
|
366
|
-
|
|
422
|
+
tokens=tokens,
|
|
423
|
+
)
|
|
424
|
+
try:
|
|
425
|
+
return self._decode(response)
|
|
426
|
+
except AuthenticationError as error:
|
|
427
|
+
if (
|
|
428
|
+
not can_refresh
|
|
429
|
+
or tokens is None
|
|
430
|
+
or error.status_code != 401
|
|
431
|
+
or isinstance(error, (SessionRevokedError, SessionBindingError))
|
|
432
|
+
):
|
|
433
|
+
raise
|
|
434
|
+
replacement = self._renew(tokens)
|
|
435
|
+
if replacement is None:
|
|
436
|
+
raise
|
|
437
|
+
response = self._send(
|
|
438
|
+
normalized_method,
|
|
439
|
+
path,
|
|
440
|
+
params=params,
|
|
441
|
+
json=json,
|
|
442
|
+
headers=headers,
|
|
443
|
+
tokens=replacement,
|
|
367
444
|
)
|
|
368
|
-
if (
|
|
369
|
-
response.status_code == 401
|
|
370
|
-
and authenticated
|
|
371
|
-
and allow_refresh
|
|
372
|
-
and self._tokens.refresh_token
|
|
373
|
-
):
|
|
374
|
-
self._refresh_after_unauthorized(failed_token)
|
|
375
|
-
response = self._send(
|
|
376
|
-
normalized_method,
|
|
377
|
-
path,
|
|
378
|
-
params=params,
|
|
379
|
-
json=json,
|
|
380
|
-
headers=headers,
|
|
381
|
-
authenticated=authenticated,
|
|
382
|
-
)
|
|
383
445
|
return self._decode(response)
|
|
384
446
|
|
|
385
447
|
def _send(
|
|
@@ -390,19 +452,16 @@ class Sub2API:
|
|
|
390
452
|
params: Mapping[str, Any] | None,
|
|
391
453
|
json: Any,
|
|
392
454
|
headers: Mapping[str, str] | None,
|
|
393
|
-
|
|
455
|
+
tokens: SessionTokens | None,
|
|
394
456
|
) -> Any:
|
|
395
457
|
relative_path = _request_path(path)
|
|
396
458
|
request_headers = {
|
|
397
459
|
"Accept": "application/json",
|
|
398
460
|
"Accept-Language": self.language,
|
|
399
|
-
"User-Agent": "sub2api-python/0.2.0",
|
|
400
461
|
"X-User-UI-Request": "1",
|
|
401
462
|
}
|
|
402
|
-
if
|
|
403
|
-
request_headers["Authorization"] =
|
|
404
|
-
f"{self._tokens.token_type} {self._tokens.access_token}"
|
|
405
|
-
)
|
|
463
|
+
if tokens is not None and tokens.access_token:
|
|
464
|
+
request_headers["Authorization"] = f"{tokens.token_type} {tokens.access_token}"
|
|
406
465
|
if headers:
|
|
407
466
|
request_headers.update(headers)
|
|
408
467
|
try:
|
|
@@ -426,6 +485,8 @@ class Sub2API:
|
|
|
426
485
|
try:
|
|
427
486
|
payload = response.json()
|
|
428
487
|
except ValueError as error:
|
|
488
|
+
if response.status_code in (401, 429) or response.status_code >= 500:
|
|
489
|
+
self._raise_api_error(response, {})
|
|
429
490
|
if not _success(response):
|
|
430
491
|
raise ProtocolError(
|
|
431
492
|
f"Sub2API returned non-JSON HTTP {response.status_code}"
|
|
@@ -455,6 +516,11 @@ class Sub2API:
|
|
|
455
516
|
if _success(response) and isinstance(code, int) and 400 <= code <= 599:
|
|
456
517
|
status_code = code
|
|
457
518
|
error_type = _ERROR_TYPES.get(status_code, APIError)
|
|
519
|
+
if 400 <= status_code < 500 and status_code != 429:
|
|
520
|
+
for identifier in (reason, code):
|
|
521
|
+
if isinstance(identifier, str) and identifier in _SESSION_ERROR_TYPES:
|
|
522
|
+
error_type = _SESSION_ERROR_TYPES[identifier]
|
|
523
|
+
break
|
|
458
524
|
raise error_type(
|
|
459
525
|
str(message),
|
|
460
526
|
status_code=status_code,
|
|
@@ -464,16 +530,79 @@ class Sub2API:
|
|
|
464
530
|
retry_after=_retry_after(response),
|
|
465
531
|
)
|
|
466
532
|
|
|
467
|
-
def
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
self.refresh()
|
|
471
|
-
|
|
472
|
-
def _refresh_after_unauthorized(self, failed_token: str | None) -> None:
|
|
533
|
+
def _renew(
|
|
534
|
+
self, observed: SessionTokens, *, only_if_expiring: bool = False
|
|
535
|
+
) -> SessionTokens | None:
|
|
473
536
|
with self._refresh_lock:
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
537
|
+
with self._auth_lock:
|
|
538
|
+
had_pending_save = self._pending_save is not None
|
|
539
|
+
if had_pending_save:
|
|
540
|
+
self._save_rotation()
|
|
541
|
+
else:
|
|
542
|
+
self._reload_tokens()
|
|
543
|
+
current = self._tokens
|
|
544
|
+
if current.authenticated and (current != observed or had_pending_save):
|
|
545
|
+
return current
|
|
546
|
+
if not current.refresh_token or (only_if_expiring and not current.needs_refresh()):
|
|
547
|
+
return None
|
|
548
|
+
try:
|
|
549
|
+
rotated = self._request_rotation(current.refresh_token)
|
|
550
|
+
except (APIError, TransportError) as error:
|
|
551
|
+
rejected = isinstance(error, APIError) and _refresh_rejected(error)
|
|
552
|
+
if rejected or isinstance(error, TransportError):
|
|
553
|
+
with self._auth_lock:
|
|
554
|
+
self._reload_tokens()
|
|
555
|
+
if self._tokens is not current and self._tokens.authenticated:
|
|
556
|
+
return self._tokens
|
|
557
|
+
if rejected and self._tokens is current:
|
|
558
|
+
self._clear_tokens()
|
|
559
|
+
raise
|
|
560
|
+
with self._auth_lock:
|
|
561
|
+
if self._tokens is current:
|
|
562
|
+
if self._token_store is not None:
|
|
563
|
+
self._pending_save = current
|
|
564
|
+
self._tokens = rotated
|
|
565
|
+
self._save_rotation()
|
|
566
|
+
return self._tokens if self._tokens.authenticated else None
|
|
567
|
+
|
|
568
|
+
def _request_rotation(self, refresh_token: str) -> SessionTokens:
|
|
569
|
+
data = self._request(
|
|
570
|
+
"POST",
|
|
571
|
+
"auth/refresh",
|
|
572
|
+
json={"refresh_token": refresh_token},
|
|
573
|
+
authenticated=False,
|
|
574
|
+
allow_refresh=False,
|
|
575
|
+
)
|
|
576
|
+
auth = self._auth_mapping(data, "token refresh")
|
|
577
|
+
access_token = auth.get("access_token")
|
|
578
|
+
rotated_token = auth.get("refresh_token")
|
|
579
|
+
if not isinstance(access_token, str) or not access_token.strip():
|
|
580
|
+
raise ProtocolError("token refresh did not return an access token")
|
|
581
|
+
if not isinstance(rotated_token, str) or not rotated_token.strip():
|
|
582
|
+
raise ProtocolError("token refresh did not return a refresh token")
|
|
583
|
+
return self._tokens_from_auth(auth)
|
|
584
|
+
|
|
585
|
+
def _reload_tokens(self) -> None:
|
|
586
|
+
if self._token_store is not None and self._pending_save is None:
|
|
587
|
+
stored = self._token_store.load() or SessionTokens()
|
|
588
|
+
if stored != self._tokens:
|
|
589
|
+
self._tokens = stored
|
|
590
|
+
|
|
591
|
+
def _save_rotation(self) -> None:
|
|
592
|
+
store, previous = self._token_store, self._pending_save
|
|
593
|
+
if store is not None and previous is not None:
|
|
594
|
+
if not store.compare_and_set(previous, self._tokens):
|
|
595
|
+
self._tokens = store.load() or SessionTokens()
|
|
596
|
+
self._pending_save = None
|
|
597
|
+
|
|
598
|
+
def _clear_tokens(self) -> None:
|
|
599
|
+
store, current, previous = self._token_store, self._tokens, self._pending_save
|
|
600
|
+
empty = SessionTokens()
|
|
601
|
+
self._tokens = empty
|
|
602
|
+
self._pending_save = None
|
|
603
|
+
self._pending_2fa_token = None
|
|
604
|
+
if store is not None and not store.compare_and_set(current, empty) and previous is not None:
|
|
605
|
+
store.compare_and_set(previous, empty)
|
|
477
606
|
|
|
478
607
|
def _auth_mapping(self, data: Any, operation: str) -> Mapping[str, Any]:
|
|
479
608
|
if not isinstance(data, Mapping):
|
|
@@ -487,19 +616,31 @@ class Sub2API:
|
|
|
487
616
|
user_data = auth.get("user")
|
|
488
617
|
if not isinstance(user_data, Mapping):
|
|
489
618
|
raise ProtocolError("login did not return a user profile")
|
|
490
|
-
|
|
619
|
+
tokens = self._tokens_from_auth(auth)
|
|
620
|
+
with self._auth_lock:
|
|
621
|
+
if self._token_store is not None:
|
|
622
|
+
self._token_store.save(tokens)
|
|
623
|
+
self._tokens = tokens
|
|
624
|
+
self._pending_save = None
|
|
491
625
|
return User(user_data)
|
|
492
626
|
|
|
493
627
|
def _tokens_from_auth(self, auth: Mapping[str, Any]) -> SessionTokens:
|
|
494
628
|
expires_in = auth.get("expires_in")
|
|
495
629
|
expires_at = None
|
|
496
|
-
if
|
|
630
|
+
if (
|
|
631
|
+
isinstance(expires_in, (int, float))
|
|
632
|
+
and not isinstance(expires_in, bool)
|
|
633
|
+
and math.isfinite(expires_in)
|
|
634
|
+
):
|
|
497
635
|
expires_at = time.time() + max(0.0, float(expires_in))
|
|
498
636
|
token_type = auth.get("token_type")
|
|
637
|
+
refresh_token = auth.get("refresh_token")
|
|
499
638
|
return SessionTokens(
|
|
500
639
|
access_token=str(auth["access_token"]),
|
|
501
640
|
refresh_token=(
|
|
502
|
-
str(
|
|
641
|
+
str(refresh_token)
|
|
642
|
+
if not self._externally_managed and refresh_token not in (None, "")
|
|
643
|
+
else None
|
|
503
644
|
),
|
|
504
645
|
expires_at=expires_at,
|
|
505
646
|
token_type=str(token_type) if token_type else "Bearer",
|
|
@@ -50,6 +50,18 @@ class AuthenticationError(APIError):
|
|
|
50
50
|
"""Raised when login or session authentication fails."""
|
|
51
51
|
|
|
52
52
|
|
|
53
|
+
class SessionExpiredError(AuthenticationError):
|
|
54
|
+
"""Raised when the instance reports that a session token expired."""
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class SessionRevokedError(AuthenticationError):
|
|
58
|
+
"""Raised when the instance reports that a session was revoked."""
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class SessionBindingError(AuthenticationError):
|
|
62
|
+
"""Raised when the request no longer matches the session binding."""
|
|
63
|
+
|
|
64
|
+
|
|
53
65
|
class PermissionDeniedError(APIError):
|
|
54
66
|
"""Raised when the user cannot perform an operation."""
|
|
55
67
|
|
|
@@ -199,7 +199,7 @@ class Balance:
|
|
|
199
199
|
|
|
200
200
|
@dataclass(frozen=True)
|
|
201
201
|
class SessionTokens:
|
|
202
|
-
"""
|
|
202
|
+
"""A snapshot of the dashboard session tokens and their expiry."""
|
|
203
203
|
|
|
204
204
|
access_token: str | None = field(default=None, repr=False)
|
|
205
205
|
refresh_token: str | None = field(default=None, repr=False)
|
|
@@ -218,7 +218,7 @@ class SessionTokens:
|
|
|
218
218
|
|
|
219
219
|
def needs_refresh(self, leeway: float = 30.0) -> bool:
|
|
220
220
|
return (
|
|
221
|
-
self.refresh_token
|
|
221
|
+
bool(self.refresh_token)
|
|
222
222
|
and self.expires_at is not None
|
|
223
223
|
and self.expires_at <= time.time() + leeway
|
|
224
224
|
)
|