spooled 1.2.2__tar.gz → 1.3.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.
- {spooled-1.2.2 → spooled-1.3.0}/PKG-INFO +15 -7
- {spooled-1.2.2 → spooled-1.3.0}/README.md +14 -6
- {spooled-1.2.2 → spooled-1.3.0}/pyproject.toml +1 -1
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/_version.py +1 -1
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/async_client.py +67 -54
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/client.py +50 -51
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/config.py +37 -2
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/errors.py +122 -13
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/client.py +43 -27
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/sse.py +195 -61
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/unified.py +77 -3
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/jobs.py +28 -8
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/organizations.py +24 -4
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/queues.py +6 -2
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/workers.py +12 -2
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/workflows.py +0 -1
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/jobs.py +24 -2
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/schedules.py +4 -4
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/workflows.py +12 -5
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/async_http.py +27 -12
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/http.py +26 -7
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/retry.py +6 -4
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/async_worker.py +258 -140
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/worker.py +258 -112
- {spooled-1.2.2 → spooled-1.3.0}/.gitignore +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/LICENSE +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/proto/spooled.proto +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/spooled_pb2.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/spooled_pb2.pyi +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/spooled_pb2_grpc.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/py.typed +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/events.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/websocket.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/admin.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/api_keys.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/auth.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/base.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/billing.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/dashboard.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/health.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/ingest.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/metrics.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/schedules.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/webhooks.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/admin.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/api_keys.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/auth.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/billing.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/common.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/dashboard.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/health.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/organizations.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/queues.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/webhooks.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/workers.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/casing.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/circuit_breaker.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/jwt.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/__init__.py +0 -0
- {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/types.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: spooled
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.3.0
|
|
4
4
|
Summary: Official Python SDK for Spooled Cloud job queue service
|
|
5
5
|
Project-URL: Homepage, https://spooled.cloud
|
|
6
6
|
Project-URL: Documentation, https://spooled.cloud/docs/
|
|
@@ -140,9 +140,14 @@ def handle_job(ctx):
|
|
|
140
140
|
def on_completed(event):
|
|
141
141
|
print(f"Job {event.job_id} completed!")
|
|
142
142
|
|
|
143
|
-
worker.start() # Blocking
|
|
143
|
+
worker.start() # Blocking; returns after worker.stop() has drained running jobs
|
|
144
144
|
```
|
|
145
145
|
|
|
146
|
+
`worker.stop()` (call it from a SIGTERM/SIGINT handler) stops claiming jobs, lets running
|
|
147
|
+
handlers finish for up to `shutdown_timeout` seconds and still acks their results, then
|
|
148
|
+
deregisters. A handler is only signalled (`ctx.signal`) and failed once it outlives that
|
|
149
|
+
timeout or the job's own `timeout_seconds`. See [docs/WORKER.md](docs/WORKER.md).
|
|
150
|
+
|
|
146
151
|
## Real-world examples (beginner friendly)
|
|
147
152
|
|
|
148
153
|
If you want 5 copy/paste “real life” setups (Stripe → jobs, GitHub Actions → jobs, cron schedules, CSV import, website signup), see:
|
|
@@ -229,7 +234,8 @@ The SDK includes a high-performance gRPC client for high-throughput worker scena
|
|
|
229
234
|
```python
|
|
230
235
|
from spooled.grpc import SpooledGrpcClient
|
|
231
236
|
|
|
232
|
-
# Connect to Spooled Cloud gRPC (TLS required for Cloudflare Tunnel)
|
|
237
|
+
# Connect to Spooled Cloud gRPC (TLS required for Cloudflare Tunnel).
|
|
238
|
+
# `SpooledClient(api_key=...).grpc` does this for you and honours `grpc_address=`.
|
|
233
239
|
client = SpooledGrpcClient(
|
|
234
240
|
address="grpc.spooled.cloud:443",
|
|
235
241
|
api_key="sp_live_...",
|
|
@@ -305,6 +311,7 @@ from spooled.errors import (
|
|
|
305
311
|
NotFoundError,
|
|
306
312
|
ValidationError,
|
|
307
313
|
RateLimitError,
|
|
314
|
+
QuotaExceededError,
|
|
308
315
|
)
|
|
309
316
|
|
|
310
317
|
client = SpooledClient(api_key="sp_live_...")
|
|
@@ -315,9 +322,10 @@ except NotFoundError:
|
|
|
315
322
|
print("Job not found")
|
|
316
323
|
except RateLimitError as e:
|
|
317
324
|
# 429 covers both per-second rate limiting and plan-quota errors.
|
|
318
|
-
# A plan quota
|
|
319
|
-
|
|
320
|
-
|
|
325
|
+
# A plan quota is a QuotaExceededError (code "QUOTA_EXCEEDED", with
|
|
326
|
+
# resource/current/limit/plan): it is never retried, because it will not clear in seconds.
|
|
327
|
+
if isinstance(e, QuotaExceededError):
|
|
328
|
+
print(f"Plan quota exceeded: {e.message} ({e.current}/{e.limit} on {e.plan})")
|
|
321
329
|
else:
|
|
322
330
|
print(f"Rate limited. Retry after {e.retry_after}s")
|
|
323
331
|
except SpooledError as e:
|
|
@@ -369,7 +377,7 @@ except SpooledError as e:
|
|
|
369
377
|
- gRPC extra: `grpcio>=1.80.0`, `grpcio-tools>=1.80.0`, `protobuf>=6.33.5`
|
|
370
378
|
- Realtime extra: `websockets>=12.0`, `sseclient-py>=1.8.0`
|
|
371
379
|
|
|
372
|
-
The package version is defined in `pyproject.toml`. At runtime, `spooled.__version__`, the default REST `User-Agent`, worker options, and REST/gRPC worker registration read installed package metadata; source-only imports fall back to `1.
|
|
380
|
+
The package version is defined in `pyproject.toml`. At runtime, `spooled.__version__`, the default REST `User-Agent`, worker options, and REST/gRPC worker registration read installed package metadata; source-only imports fall back to `1.3.0`.
|
|
373
381
|
|
|
374
382
|
Release maintainers should follow the [publishing checklist](docs/PUBLISHING.md) before creating a tag or publishing to PyPI.
|
|
375
383
|
|
|
@@ -91,9 +91,14 @@ def handle_job(ctx):
|
|
|
91
91
|
def on_completed(event):
|
|
92
92
|
print(f"Job {event.job_id} completed!")
|
|
93
93
|
|
|
94
|
-
worker.start() # Blocking
|
|
94
|
+
worker.start() # Blocking; returns after worker.stop() has drained running jobs
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
+
`worker.stop()` (call it from a SIGTERM/SIGINT handler) stops claiming jobs, lets running
|
|
98
|
+
handlers finish for up to `shutdown_timeout` seconds and still acks their results, then
|
|
99
|
+
deregisters. A handler is only signalled (`ctx.signal`) and failed once it outlives that
|
|
100
|
+
timeout or the job's own `timeout_seconds`. See [docs/WORKER.md](docs/WORKER.md).
|
|
101
|
+
|
|
97
102
|
## Real-world examples (beginner friendly)
|
|
98
103
|
|
|
99
104
|
If you want 5 copy/paste “real life” setups (Stripe → jobs, GitHub Actions → jobs, cron schedules, CSV import, website signup), see:
|
|
@@ -180,7 +185,8 @@ The SDK includes a high-performance gRPC client for high-throughput worker scena
|
|
|
180
185
|
```python
|
|
181
186
|
from spooled.grpc import SpooledGrpcClient
|
|
182
187
|
|
|
183
|
-
# Connect to Spooled Cloud gRPC (TLS required for Cloudflare Tunnel)
|
|
188
|
+
# Connect to Spooled Cloud gRPC (TLS required for Cloudflare Tunnel).
|
|
189
|
+
# `SpooledClient(api_key=...).grpc` does this for you and honours `grpc_address=`.
|
|
184
190
|
client = SpooledGrpcClient(
|
|
185
191
|
address="grpc.spooled.cloud:443",
|
|
186
192
|
api_key="sp_live_...",
|
|
@@ -256,6 +262,7 @@ from spooled.errors import (
|
|
|
256
262
|
NotFoundError,
|
|
257
263
|
ValidationError,
|
|
258
264
|
RateLimitError,
|
|
265
|
+
QuotaExceededError,
|
|
259
266
|
)
|
|
260
267
|
|
|
261
268
|
client = SpooledClient(api_key="sp_live_...")
|
|
@@ -266,9 +273,10 @@ except NotFoundError:
|
|
|
266
273
|
print("Job not found")
|
|
267
274
|
except RateLimitError as e:
|
|
268
275
|
# 429 covers both per-second rate limiting and plan-quota errors.
|
|
269
|
-
# A plan quota
|
|
270
|
-
|
|
271
|
-
|
|
276
|
+
# A plan quota is a QuotaExceededError (code "QUOTA_EXCEEDED", with
|
|
277
|
+
# resource/current/limit/plan): it is never retried, because it will not clear in seconds.
|
|
278
|
+
if isinstance(e, QuotaExceededError):
|
|
279
|
+
print(f"Plan quota exceeded: {e.message} ({e.current}/{e.limit} on {e.plan})")
|
|
272
280
|
else:
|
|
273
281
|
print(f"Rate limited. Retry after {e.retry_after}s")
|
|
274
282
|
except SpooledError as e:
|
|
@@ -320,7 +328,7 @@ except SpooledError as e:
|
|
|
320
328
|
- gRPC extra: `grpcio>=1.80.0`, `grpcio-tools>=1.80.0`, `protobuf>=6.33.5`
|
|
321
329
|
- Realtime extra: `websockets>=12.0`, `sseclient-py>=1.8.0`
|
|
322
330
|
|
|
323
|
-
The package version is defined in `pyproject.toml`. At runtime, `spooled.__version__`, the default REST `User-Agent`, worker options, and REST/gRPC worker registration read installed package metadata; source-only imports fall back to `1.
|
|
331
|
+
The package version is defined in `pyproject.toml`. At runtime, `spooled.__version__`, the default REST `User-Agent`, worker options, and REST/gRPC worker registration read installed package metadata; source-only imports fall back to `1.3.0`.
|
|
324
332
|
|
|
325
333
|
Release maintainers should follow the [publishing checklist](docs/PUBLISHING.md) before creating a tag or publishing to PyPI.
|
|
326
334
|
|
|
@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Any, Literal
|
|
|
13
13
|
from spooled.config import (
|
|
14
14
|
ResolvedConfig,
|
|
15
15
|
SpooledClientConfig,
|
|
16
|
+
merge_client_config,
|
|
16
17
|
resolve_config,
|
|
17
18
|
validate_config,
|
|
18
19
|
)
|
|
@@ -244,7 +245,7 @@ class AsyncSpooledClient:
|
|
|
244
245
|
The gRPC client is created on first access.
|
|
245
246
|
|
|
246
247
|
Example:
|
|
247
|
-
>>> job = client.grpc.enqueue(
|
|
248
|
+
>>> job = client.grpc.queue.enqueue(
|
|
248
249
|
... queue_name="test",
|
|
249
250
|
... payload={"task": "process"}
|
|
250
251
|
... )
|
|
@@ -257,22 +258,12 @@ class AsyncSpooledClient:
|
|
|
257
258
|
"gRPC package required. Install with: pip install spooled[grpc]"
|
|
258
259
|
) from e
|
|
259
260
|
|
|
260
|
-
#
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
grpc_url = base_url.replace("http://", "")
|
|
267
|
-
use_tls = False
|
|
268
|
-
else:
|
|
269
|
-
grpc_url = base_url
|
|
270
|
-
use_tls = True
|
|
271
|
-
|
|
272
|
-
# Extract host and use default gRPC port
|
|
273
|
-
host = grpc_url.split(":")[0] if ":" in grpc_url else grpc_url
|
|
274
|
-
grpc_port = 50051
|
|
275
|
-
grpc_url = f"{host}:{grpc_port}"
|
|
261
|
+
# Use the configured gRPC address (default: grpc.spooled.cloud:443, as in
|
|
262
|
+
# the docs and the other SDKs). It is a different host/port from the REST
|
|
263
|
+
# API, so it must not be derived from base_url; self-hosted servers set
|
|
264
|
+
# ``grpc_address`` explicitly. TLS is auto-detected: on unless the host
|
|
265
|
+
# is localhost.
|
|
266
|
+
grpc_address = self._config.grpc_address
|
|
276
267
|
|
|
277
268
|
# Get API key or token for auth
|
|
278
269
|
api_key = self._config.api_key
|
|
@@ -280,9 +271,8 @@ class AsyncSpooledClient:
|
|
|
280
271
|
api_key = self._config.access_token
|
|
281
272
|
|
|
282
273
|
self._grpc = SpooledGrpcClient(
|
|
283
|
-
address=
|
|
274
|
+
address=grpc_address,
|
|
284
275
|
api_key=api_key or "",
|
|
285
|
-
use_tls=use_tls,
|
|
286
276
|
)
|
|
287
277
|
|
|
288
278
|
return self._grpc
|
|
@@ -335,13 +325,25 @@ class AsyncSpooledClient:
|
|
|
335
325
|
# API key for one first rather than forwarding the raw key (which the
|
|
336
326
|
# server rejects on the WS handshake). The cached JWT is reused here, so
|
|
337
327
|
# repeated realtime() calls do not each hit the login endpoint. The
|
|
338
|
-
# unified realtime client is synchronous
|
|
339
|
-
#
|
|
340
|
-
# it reuses this token across reconnects.
|
|
328
|
+
# unified realtime client is synchronous: it reconnects on background
|
|
329
|
+
# threads, which call back into this client for a fresh token below.
|
|
341
330
|
token = await self.get_jwt_token()
|
|
331
|
+
loop = asyncio.get_running_loop()
|
|
332
|
+
|
|
333
|
+
def token_provider() -> str:
|
|
334
|
+
try:
|
|
335
|
+
on_loop = asyncio.get_running_loop() is loop
|
|
336
|
+
except RuntimeError:
|
|
337
|
+
on_loop = False
|
|
338
|
+
if on_loop:
|
|
339
|
+
# connect() called from async code: blocking on a coroutine of this
|
|
340
|
+
# very loop would deadlock, so reuse the newest token minted so far.
|
|
341
|
+
return self._cached_jwt or self._config.access_token or token
|
|
342
|
+
return asyncio.run_coroutine_threadsafe(self.get_jwt_token(), loop).result(30)
|
|
342
343
|
|
|
343
344
|
options = SpooledRealtimeOptions(
|
|
344
345
|
base_url=self._config.base_url,
|
|
346
|
+
ws_url=self._config.ws_url,
|
|
345
347
|
token=token,
|
|
346
348
|
type=type,
|
|
347
349
|
auto_reconnect=auto_reconnect,
|
|
@@ -349,6 +351,9 @@ class AsyncSpooledClient:
|
|
|
349
351
|
reconnect_delay=reconnect_delay,
|
|
350
352
|
max_reconnect_delay=max_reconnect_delay,
|
|
351
353
|
debug=self._config.debug_fn,
|
|
354
|
+
# Each (re)connect on a background thread mints a token via the cached
|
|
355
|
+
# exchange, so long-lived streams survive JWT expiry.
|
|
356
|
+
token_provider=token_provider,
|
|
352
357
|
)
|
|
353
358
|
|
|
354
359
|
return SpooledRealtime(options)
|
|
@@ -379,7 +384,9 @@ class AsyncSpooledClient:
|
|
|
379
384
|
base_url: Override base URL
|
|
380
385
|
timeout: Override timeout
|
|
381
386
|
debug: Override debug flag
|
|
382
|
-
**kwargs:
|
|
387
|
+
**kwargs: Any other ``SpooledClientConfig`` field to override
|
|
388
|
+
(``headers``, ``retry``, ``circuit_breaker``, ``ws_url``,
|
|
389
|
+
``grpc_address``, ``connect_timeout``, ``user_agent``, ...)
|
|
383
390
|
|
|
384
391
|
Returns:
|
|
385
392
|
New AsyncSpooledClient instance
|
|
@@ -391,44 +398,44 @@ class AsyncSpooledClient:
|
|
|
391
398
|
>>> # Create client with different API key
|
|
392
399
|
>>> other_client = client.with_options(api_key="sk_live_other")
|
|
393
400
|
"""
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
"
|
|
397
|
-
"
|
|
398
|
-
"
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
"
|
|
402
|
-
|
|
403
|
-
"timeout": timeout if timeout is not None else self._config.timeout,
|
|
404
|
-
"debug": debug if debug is not None else (self._config.debug_fn is not None),
|
|
401
|
+
overrides: dict[str, Any] = {
|
|
402
|
+
"api_key": api_key,
|
|
403
|
+
"access_token": access_token,
|
|
404
|
+
"refresh_token": refresh_token,
|
|
405
|
+
"admin_key": admin_key,
|
|
406
|
+
"base_url": base_url,
|
|
407
|
+
"timeout": timeout,
|
|
408
|
+
"debug": debug,
|
|
409
|
+
**kwargs,
|
|
405
410
|
}
|
|
406
411
|
|
|
407
|
-
#
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
new_config = {k: v for k, v in new_config.items() if v is not None}
|
|
412
|
-
|
|
413
|
-
return AsyncSpooledClient(**new_config)
|
|
412
|
+
# Carry over the whole current configuration (headers, retry, circuit
|
|
413
|
+
# breaker, user agent, timeouts, gRPC address, WebSocket URL), not just
|
|
414
|
+
# the credentials: an allow-list here silently reset everything else.
|
|
415
|
+
return AsyncSpooledClient(config=merge_client_config(self._config, overrides))
|
|
414
416
|
|
|
415
417
|
# Token management
|
|
416
418
|
|
|
417
419
|
async def get_jwt_token(self, *, force_refresh: bool = False) -> str:
|
|
418
420
|
"""Get or acquire a JWT token for realtime connections.
|
|
419
421
|
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
422
|
+
The token is for the realtime transport only: it is never installed as
|
|
423
|
+
the REST client's bearer, so an API-key client keeps authenticating its
|
|
424
|
+
REST calls with the key (a JWT swapped in here expired after 24 h with
|
|
425
|
+
nothing to renew it).
|
|
426
|
+
|
|
427
|
+
A statically configured ``access_token`` is returned as-is; when a
|
|
428
|
+
``refresh_token`` is also configured it is renewed shortly before it
|
|
429
|
+
expires. When only an API key is available, the JWT obtained from
|
|
430
|
+
``/auth/login`` is cached and reused across (re)connects until it is
|
|
431
|
+
near expiry (decoded from the token's ``exp`` claim, refreshed ~60s
|
|
432
|
+
early). This keeps reconnect storms from repeatedly hitting the login
|
|
433
|
+
rate limiter. Pass ``force_refresh=True`` to bypass the cache, e.g.
|
|
434
|
+
after the server rejects the current token on a WebSocket handshake.
|
|
429
435
|
"""
|
|
430
|
-
# A user-supplied
|
|
436
|
+
# A user-supplied access token is used as-is, renewed only when we can.
|
|
431
437
|
if self._config.access_token:
|
|
438
|
+
await self._refresh_static_token_if_due()
|
|
432
439
|
return self._config.access_token
|
|
433
440
|
|
|
434
441
|
if not self._config.api_key:
|
|
@@ -443,13 +450,19 @@ class AsyncSpooledClient:
|
|
|
443
450
|
return self._cached_jwt
|
|
444
451
|
|
|
445
452
|
response = await self.auth.login({"api_key": self._config.api_key})
|
|
446
|
-
self._http.set_auth_token(response.access_token)
|
|
447
|
-
# Keep the refresh token for the HTTP layer's auto-refresh path.
|
|
448
|
-
self._config.refresh_token = response.refresh_token
|
|
449
453
|
self._cached_jwt = response.access_token
|
|
450
454
|
self._cached_jwt_exp = decode_jwt_exp(response.access_token)
|
|
451
455
|
return self._cached_jwt
|
|
452
456
|
|
|
457
|
+
async def _refresh_static_token_if_due(self) -> None:
|
|
458
|
+
"""Renew a configured access token that is about to expire (needs a refresh token)."""
|
|
459
|
+
config = self._config
|
|
460
|
+
if not (config.access_token and config.refresh_token and config.auto_refresh_token):
|
|
461
|
+
return
|
|
462
|
+
exp = decode_jwt_exp(config.access_token)
|
|
463
|
+
if exp is not None and jwt_needs_refresh(exp, time.time()):
|
|
464
|
+
await self._http.refresh_now()
|
|
465
|
+
|
|
453
466
|
async def _refresh_access_token(self) -> str:
|
|
454
467
|
"""Refresh the access token."""
|
|
455
468
|
if not self._config.refresh_token:
|
|
@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Any, Literal
|
|
|
13
13
|
from spooled.config import (
|
|
14
14
|
ResolvedConfig,
|
|
15
15
|
SpooledClientConfig,
|
|
16
|
+
merge_client_config,
|
|
16
17
|
resolve_config,
|
|
17
18
|
validate_config,
|
|
18
19
|
)
|
|
@@ -253,7 +254,7 @@ class SpooledClient:
|
|
|
253
254
|
The gRPC client is created on first access.
|
|
254
255
|
|
|
255
256
|
Example:
|
|
256
|
-
>>> job = client.grpc.enqueue(
|
|
257
|
+
>>> job = client.grpc.queue.enqueue(
|
|
257
258
|
... queue_name="test",
|
|
258
259
|
... payload={"task": "process"}
|
|
259
260
|
... )
|
|
@@ -266,22 +267,12 @@ class SpooledClient:
|
|
|
266
267
|
"gRPC package required. Install with: pip install spooled[grpc]"
|
|
267
268
|
) from e
|
|
268
269
|
|
|
269
|
-
#
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
grpc_url = base_url.replace("http://", "")
|
|
276
|
-
use_tls = False
|
|
277
|
-
else:
|
|
278
|
-
grpc_url = base_url
|
|
279
|
-
use_tls = True
|
|
280
|
-
|
|
281
|
-
# Extract host and use default gRPC port
|
|
282
|
-
host = grpc_url.split(":")[0] if ":" in grpc_url else grpc_url
|
|
283
|
-
grpc_port = 50051
|
|
284
|
-
grpc_url = f"{host}:{grpc_port}"
|
|
270
|
+
# Use the configured gRPC address (default: grpc.spooled.cloud:443, as in
|
|
271
|
+
# the docs and the other SDKs). It is a different host/port from the REST
|
|
272
|
+
# API, so it must not be derived from base_url; self-hosted servers set
|
|
273
|
+
# ``grpc_address`` explicitly. TLS is auto-detected: on unless the host
|
|
274
|
+
# is localhost.
|
|
275
|
+
grpc_address = self._config.grpc_address
|
|
285
276
|
|
|
286
277
|
# Get API key or token for auth
|
|
287
278
|
api_key = self._config.api_key
|
|
@@ -289,9 +280,8 @@ class SpooledClient:
|
|
|
289
280
|
api_key = self._config.access_token
|
|
290
281
|
|
|
291
282
|
self._grpc = SpooledGrpcClient(
|
|
292
|
-
address=
|
|
283
|
+
address=grpc_address,
|
|
293
284
|
api_key=api_key or "",
|
|
294
|
-
use_tls=use_tls,
|
|
295
285
|
)
|
|
296
286
|
|
|
297
287
|
return self._grpc
|
|
@@ -345,6 +335,7 @@ class SpooledClient:
|
|
|
345
335
|
|
|
346
336
|
options = SpooledRealtimeOptions(
|
|
347
337
|
base_url=self._config.base_url,
|
|
338
|
+
ws_url=self._config.ws_url,
|
|
348
339
|
token=token,
|
|
349
340
|
type=type,
|
|
350
341
|
auto_reconnect=auto_reconnect,
|
|
@@ -386,7 +377,9 @@ class SpooledClient:
|
|
|
386
377
|
base_url: Override base URL
|
|
387
378
|
timeout: Override timeout
|
|
388
379
|
debug: Override debug flag
|
|
389
|
-
**kwargs:
|
|
380
|
+
**kwargs: Any other ``SpooledClientConfig`` field to override
|
|
381
|
+
(``headers``, ``retry``, ``circuit_breaker``, ``ws_url``,
|
|
382
|
+
``grpc_address``, ``connect_timeout``, ``user_agent``, ...)
|
|
390
383
|
|
|
391
384
|
Returns:
|
|
392
385
|
New SpooledClient instance
|
|
@@ -398,44 +391,44 @@ class SpooledClient:
|
|
|
398
391
|
>>> # Create client with different API key
|
|
399
392
|
>>> other_client = client.with_options(api_key="sk_live_other")
|
|
400
393
|
"""
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
"
|
|
404
|
-
"
|
|
405
|
-
"
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
"
|
|
409
|
-
|
|
410
|
-
"timeout": timeout if timeout is not None else self._config.timeout,
|
|
411
|
-
"debug": debug if debug is not None else (self._config.debug_fn is not None),
|
|
394
|
+
overrides: dict[str, Any] = {
|
|
395
|
+
"api_key": api_key,
|
|
396
|
+
"access_token": access_token,
|
|
397
|
+
"refresh_token": refresh_token,
|
|
398
|
+
"admin_key": admin_key,
|
|
399
|
+
"base_url": base_url,
|
|
400
|
+
"timeout": timeout,
|
|
401
|
+
"debug": debug,
|
|
402
|
+
**kwargs,
|
|
412
403
|
}
|
|
413
404
|
|
|
414
|
-
#
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
new_config = {k: v for k, v in new_config.items() if v is not None}
|
|
419
|
-
|
|
420
|
-
return SpooledClient(**new_config)
|
|
405
|
+
# Carry over the whole current configuration (headers, retry, circuit
|
|
406
|
+
# breaker, user agent, timeouts, gRPC address, WebSocket URL), not just
|
|
407
|
+
# the credentials: an allow-list here silently reset everything else.
|
|
408
|
+
return SpooledClient(config=merge_client_config(self._config, overrides))
|
|
421
409
|
|
|
422
410
|
# Token management
|
|
423
411
|
|
|
424
412
|
def get_jwt_token(self, *, force_refresh: bool = False) -> str:
|
|
425
413
|
"""Get or acquire a JWT token for realtime connections.
|
|
426
414
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
415
|
+
The token is for the realtime transport only: it is never installed as
|
|
416
|
+
the REST client's bearer, so an API-key client keeps authenticating its
|
|
417
|
+
REST calls with the key (a JWT swapped in here expired after 24 h with
|
|
418
|
+
nothing to renew it).
|
|
419
|
+
|
|
420
|
+
A statically configured ``access_token`` is returned as-is; when a
|
|
421
|
+
``refresh_token`` is also configured it is renewed shortly before it
|
|
422
|
+
expires. When only an API key is available, the JWT obtained from
|
|
423
|
+
``/auth/login`` is cached and reused across (re)connects until it is
|
|
424
|
+
near expiry (decoded from the token's ``exp`` claim, refreshed ~60s
|
|
425
|
+
early). This keeps reconnect storms from repeatedly hitting the login
|
|
426
|
+
rate limiter. Pass ``force_refresh=True`` to bypass the cache, e.g.
|
|
427
|
+
after the server rejects the current token on a WebSocket handshake.
|
|
436
428
|
"""
|
|
437
|
-
# A user-supplied
|
|
429
|
+
# A user-supplied access token is used as-is, renewed only when we can.
|
|
438
430
|
if self._config.access_token:
|
|
431
|
+
self._refresh_static_token_if_due()
|
|
439
432
|
return self._config.access_token
|
|
440
433
|
|
|
441
434
|
if not self._config.api_key:
|
|
@@ -450,13 +443,19 @@ class SpooledClient:
|
|
|
450
443
|
return self._cached_jwt
|
|
451
444
|
|
|
452
445
|
response = self.auth.login({"api_key": self._config.api_key})
|
|
453
|
-
self._http.set_auth_token(response.access_token)
|
|
454
|
-
# Keep the refresh token for the HTTP layer's auto-refresh path.
|
|
455
|
-
self._config.refresh_token = response.refresh_token
|
|
456
446
|
self._cached_jwt = response.access_token
|
|
457
447
|
self._cached_jwt_exp = decode_jwt_exp(response.access_token)
|
|
458
448
|
return self._cached_jwt
|
|
459
449
|
|
|
450
|
+
def _refresh_static_token_if_due(self) -> None:
|
|
451
|
+
"""Renew a configured access token that is about to expire (needs a refresh token)."""
|
|
452
|
+
config = self._config
|
|
453
|
+
if not (config.access_token and config.refresh_token and config.auto_refresh_token):
|
|
454
|
+
return
|
|
455
|
+
exp = decode_jwt_exp(config.access_token)
|
|
456
|
+
if exp is not None and jwt_needs_refresh(exp, time.time()):
|
|
457
|
+
self._http.refresh_now()
|
|
458
|
+
|
|
460
459
|
def _refresh_access_token(self) -> str:
|
|
461
460
|
"""Refresh the access token."""
|
|
462
461
|
if not self._config.refresh_token:
|
|
@@ -157,5 +157,40 @@ def resolve_config(config: SpooledClientConfig) -> ResolvedConfig:
|
|
|
157
157
|
|
|
158
158
|
def validate_config(config: ResolvedConfig) -> None:
|
|
159
159
|
"""Validate that configuration has required authentication."""
|
|
160
|
-
|
|
161
|
-
|
|
160
|
+
# An admin key alone is enough for the /admin endpoints (X-Admin-Key header).
|
|
161
|
+
if not config.api_key and not config.access_token and not config.admin_key:
|
|
162
|
+
raise ValueError(
|
|
163
|
+
"Either api_key or access_token must be provided "
|
|
164
|
+
"(or admin_key for a client that only calls the admin endpoints)"
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def merge_client_config(current: ResolvedConfig, overrides: dict[str, Any]) -> SpooledClientConfig:
|
|
169
|
+
"""Build the config for ``with_options()``: everything in ``current`` plus ``overrides``.
|
|
170
|
+
|
|
171
|
+
Every field is carried over -- headers, retry and circuit-breaker settings,
|
|
172
|
+
user agent, timeouts, gRPC address and WebSocket URL -- not just the
|
|
173
|
+
credentials and base URL. ``overrides`` entries that are ``None`` mean "keep".
|
|
174
|
+
"""
|
|
175
|
+
merged: dict[str, Any] = {
|
|
176
|
+
"api_key": current.api_key,
|
|
177
|
+
"access_token": current.access_token,
|
|
178
|
+
"refresh_token": current.refresh_token,
|
|
179
|
+
"admin_key": current.admin_key,
|
|
180
|
+
"base_url": current.base_url,
|
|
181
|
+
"grpc_address": current.grpc_address,
|
|
182
|
+
"timeout": current.timeout,
|
|
183
|
+
"connect_timeout": current.connect_timeout,
|
|
184
|
+
"retry": current.retry,
|
|
185
|
+
"circuit_breaker": current.circuit_breaker,
|
|
186
|
+
"headers": dict(current.headers),
|
|
187
|
+
"user_agent": current.user_agent,
|
|
188
|
+
"auto_refresh_token": current.auto_refresh_token,
|
|
189
|
+
"debug": current.debug_fn is not None,
|
|
190
|
+
}
|
|
191
|
+
# ``ws_url`` is always resolved, but when it was only derived from the base
|
|
192
|
+
# URL it must be derived again if ``base_url`` is overridden.
|
|
193
|
+
if current.ws_url != SpooledClientConfig(base_url=current.base_url).get_ws_url().rstrip("/"):
|
|
194
|
+
merged["ws_url"] = current.ws_url
|
|
195
|
+
merged.update({key: value for key, value in overrides.items() if value is not None})
|
|
196
|
+
return SpooledClientConfig(**merged)
|