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.
Files changed (67) hide show
  1. {spooled-1.2.2 → spooled-1.3.0}/PKG-INFO +15 -7
  2. {spooled-1.2.2 → spooled-1.3.0}/README.md +14 -6
  3. {spooled-1.2.2 → spooled-1.3.0}/pyproject.toml +1 -1
  4. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/_version.py +1 -1
  5. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/async_client.py +67 -54
  6. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/client.py +50 -51
  7. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/config.py +37 -2
  8. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/errors.py +122 -13
  9. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/client.py +43 -27
  10. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/sse.py +195 -61
  11. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/unified.py +77 -3
  12. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/jobs.py +28 -8
  13. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/organizations.py +24 -4
  14. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/queues.py +6 -2
  15. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/workers.py +12 -2
  16. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/workflows.py +0 -1
  17. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/jobs.py +24 -2
  18. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/schedules.py +4 -4
  19. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/workflows.py +12 -5
  20. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/async_http.py +27 -12
  21. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/http.py +26 -7
  22. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/retry.py +6 -4
  23. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/async_worker.py +258 -140
  24. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/worker.py +258 -112
  25. {spooled-1.2.2 → spooled-1.3.0}/.gitignore +0 -0
  26. {spooled-1.2.2 → spooled-1.3.0}/LICENSE +0 -0
  27. {spooled-1.2.2 → spooled-1.3.0}/proto/spooled.proto +0 -0
  28. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/__init__.py +0 -0
  29. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/__init__.py +0 -0
  30. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/__init__.py +0 -0
  31. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/spooled_pb2.py +0 -0
  32. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/spooled_pb2.pyi +0 -0
  33. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/grpc/stubs/spooled_pb2_grpc.py +0 -0
  34. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/py.typed +0 -0
  35. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/__init__.py +0 -0
  36. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/events.py +0 -0
  37. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/realtime/websocket.py +0 -0
  38. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/__init__.py +0 -0
  39. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/admin.py +0 -0
  40. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/api_keys.py +0 -0
  41. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/auth.py +0 -0
  42. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/base.py +0 -0
  43. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/billing.py +0 -0
  44. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/dashboard.py +0 -0
  45. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/health.py +0 -0
  46. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/ingest.py +0 -0
  47. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/metrics.py +0 -0
  48. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/schedules.py +0 -0
  49. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/resources/webhooks.py +0 -0
  50. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/__init__.py +0 -0
  51. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/admin.py +0 -0
  52. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/api_keys.py +0 -0
  53. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/auth.py +0 -0
  54. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/billing.py +0 -0
  55. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/common.py +0 -0
  56. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/dashboard.py +0 -0
  57. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/health.py +0 -0
  58. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/organizations.py +0 -0
  59. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/queues.py +0 -0
  60. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/webhooks.py +0 -0
  61. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/types/workers.py +0 -0
  62. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/__init__.py +0 -0
  63. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/casing.py +0 -0
  64. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/circuit_breaker.py +0 -0
  65. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/utils/jwt.py +0 -0
  66. {spooled-1.2.2 → spooled-1.3.0}/src/spooled/worker/__init__.py +0 -0
  67. {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.2.2
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 carries code == "QUOTA_EXCEEDED" (with resource/current/limit/plan details).
319
- if e.code == "QUOTA_EXCEEDED":
320
- print(f"Plan quota exceeded: {e.message}")
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.2.0`.
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 carries code == "QUOTA_EXCEEDED" (with resource/current/limit/plan details).
270
- if e.code == "QUOTA_EXCEEDED":
271
- print(f"Plan quota exceeded: {e.message}")
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.2.0`.
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
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "spooled"
7
- version = "1.2.2"
7
+ version = "1.3.0"
8
8
  description = "Official Python SDK for Spooled Cloud job queue service"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
5
5
  try:
6
6
  __version__ = version("spooled")
7
7
  except PackageNotFoundError: # pragma: no cover - source checkout without installed metadata
8
- __version__ = "1.2.2"
8
+ __version__ = "1.3.0"
@@ -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
- # Build gRPC URL from base URL
261
- base_url = self._config.base_url
262
- if base_url.startswith("https://"):
263
- grpc_url = base_url.replace("https://", "")
264
- use_tls = True
265
- elif base_url.startswith("http://"):
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=grpc_url,
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 (runs its reconnect loop on a
339
- # background thread) and so cannot await this coroutine per reconnect;
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: Additional configuration options
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
- # Start with current config values
395
- new_config: dict[str, Any] = {
396
- "api_key": api_key if api_key is not None else self._config.api_key,
397
- "access_token": access_token if access_token is not None else self._config.access_token,
398
- "refresh_token": refresh_token
399
- if refresh_token is not None
400
- else self._config.refresh_token,
401
- "admin_key": admin_key if admin_key is not None else self._config.admin_key,
402
- "base_url": base_url if base_url is not None else self._config.base_url,
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
- # Add any extra kwargs
408
- new_config.update(kwargs)
409
-
410
- # Remove None values
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
- A statically configured ``access_token`` is returned verbatim -- we never
421
- expire or replace it, since there may be no API key to re-login with.
422
-
423
- When only an API key is available, the JWT obtained from ``/auth/login``
424
- is cached and reused across (re)connects until it is near expiry (decoded
425
- from the token's ``exp`` claim, refreshed ~60s early). This keeps
426
- reconnect storms from repeatedly hitting the login rate limiter. Pass
427
- ``force_refresh=True`` to bypass the cache, e.g. after the server rejects
428
- the current token on a WebSocket handshake.
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 static access token is used as-is.
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
- # Build gRPC URL from base URL
270
- base_url = self._config.base_url
271
- if base_url.startswith("https://"):
272
- grpc_url = base_url.replace("https://", "")
273
- use_tls = True
274
- elif base_url.startswith("http://"):
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=grpc_url,
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: Additional configuration options
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
- # Start with current config values
402
- new_config: dict[str, Any] = {
403
- "api_key": api_key if api_key is not None else self._config.api_key,
404
- "access_token": access_token if access_token is not None else self._config.access_token,
405
- "refresh_token": refresh_token
406
- if refresh_token is not None
407
- else self._config.refresh_token,
408
- "admin_key": admin_key if admin_key is not None else self._config.admin_key,
409
- "base_url": base_url if base_url is not None else self._config.base_url,
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
- # Add any extra kwargs
415
- new_config.update(kwargs)
416
-
417
- # Remove None values
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
- A statically configured ``access_token`` is returned verbatim -- we never
428
- expire or replace it, since there may be no API key to re-login with.
429
-
430
- When only an API key is available, the JWT obtained from ``/auth/login``
431
- is cached and reused across (re)connects until it is near expiry (decoded
432
- from the token's ``exp`` claim, refreshed ~60s early). This keeps
433
- reconnect storms from repeatedly hitting the login rate limiter. Pass
434
- ``force_refresh=True`` to bypass the cache, e.g. after the server rejects
435
- the current token on a WebSocket handshake.
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 static access token is used as-is.
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
- if not config.api_key and not config.access_token:
161
- raise ValueError("Either api_key or access_token must be provided")
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)