vercel-apscheduler-bundle 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vercel_apscheduler_bundle-0.1.0/LICENSE +21 -0
- vercel_apscheduler_bundle-0.1.0/PKG-INFO +279 -0
- vercel_apscheduler_bundle-0.1.0/README.md +265 -0
- vercel_apscheduler_bundle-0.1.0/SCHEDULER.md +482 -0
- vercel_apscheduler_bundle-0.1.0/examples/cleanup/README.md +49 -0
- vercel_apscheduler_bundle-0.1.0/examples/cleanup/main.py +47 -0
- vercel_apscheduler_bundle-0.1.0/examples/cleanup/pyproject.toml +19 -0
- vercel_apscheduler_bundle-0.1.0/examples/cleanup/scheduler.py +48 -0
- vercel_apscheduler_bundle-0.1.0/examples/cleanup/vercel.json +3 -0
- vercel_apscheduler_bundle-0.1.0/pyproject.toml +146 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/__init__.py +15 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_adapter.py +1375 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_automatic.py +249 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/__init__.py +50 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/_protocols.py +197 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/__init__.py +122 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/_doc.py +29 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/_driver.py +586 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/_jobstore.py +375 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/redis/__init__.py +99 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/redis/_driver.py +983 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/redis/_jobstore.py +477 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_control.py +88 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_executor.py +140 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_imports.py +53 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_options.py +296 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_payload.py +132 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_subscriber.py +223 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_time.py +51 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_types.py +116 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_vendor/__init__.py +1 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/py.typed +1 -0
- vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/version.py +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) Vercel, Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vercel-apscheduler-bundle
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: APScheduler integration for Vercel Queues
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Requires-Dist: apscheduler<4,>=3.10.4
|
|
9
|
+
Requires-Dist: redis<7,>=5
|
|
10
|
+
Requires-Dist: vercel-cache-bundle>=0.7.2
|
|
11
|
+
Requires-Dist: vercel-internal-shared-vendored-deps>=0.1.1
|
|
12
|
+
Requires-Dist: vercel-queue-bundle>=0.7.3
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# vercel-apscheduler-bundle
|
|
16
|
+
|
|
17
|
+
This is a version of `vercel-apscheduler` with third-party dependencies bundled. For normal use, install the unbundled `vercel-apscheduler` package instead: https://pypi.org/project/vercel-apscheduler/
|
|
18
|
+
|
|
19
|
+
# Vercel APScheduler integration
|
|
20
|
+
|
|
21
|
+
Run APScheduler 3.x schedules through delayed Vercel Queue messages, with
|
|
22
|
+
Redis as the durable job store and lifecycle coordinator.
|
|
23
|
+
|
|
24
|
+
## Configure the scheduler
|
|
25
|
+
|
|
26
|
+
Use APScheduler's standard Redis job store:
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from os import environ
|
|
30
|
+
|
|
31
|
+
from apscheduler.jobstores.redis import RedisJobStore
|
|
32
|
+
from apscheduler.schedulers.blocking import BlockingScheduler
|
|
33
|
+
from redis import ConnectionPool
|
|
34
|
+
|
|
35
|
+
scheduler = BlockingScheduler(
|
|
36
|
+
timezone="UTC",
|
|
37
|
+
jobstores={
|
|
38
|
+
"default": RedisJobStore(
|
|
39
|
+
connection_pool=ConnectionPool.from_url(
|
|
40
|
+
environ["REDIS_URL"],
|
|
41
|
+
socket_connect_timeout=5,
|
|
42
|
+
socket_timeout=5,
|
|
43
|
+
),
|
|
44
|
+
)
|
|
45
|
+
},
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@scheduler.scheduled_job(
|
|
50
|
+
"cron",
|
|
51
|
+
hour=4,
|
|
52
|
+
id="cleanup",
|
|
53
|
+
replace_existing=True,
|
|
54
|
+
)
|
|
55
|
+
def cleanup() -> None: ...
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Declare that object as a Python subscriber:
|
|
59
|
+
|
|
60
|
+
```toml
|
|
61
|
+
[[tool.vercel.subscribers]]
|
|
62
|
+
entrypoint = "scheduler:scheduler"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The Vercel Python builder detects APScheduler before importing the subscriber,
|
|
66
|
+
installs the integration, and extracts its internal Queue subscriptions from
|
|
67
|
+
the same registry used by Celery and Dramatiq. Topic names, consumer groups,
|
|
68
|
+
scheduler IDs, and installation hooks are not application configuration.
|
|
69
|
+
|
|
70
|
+
No Vercel-specific job store is required. v1 requires exactly one job store,
|
|
71
|
+
named `default`, and it must be APScheduler's Redis-backed `RedisJobStore`.
|
|
72
|
+
The integration uses that store's configured Redis client for its internal
|
|
73
|
+
lifecycle coordination. A missing `REDIS_URL` fails the import with a
|
|
74
|
+
`KeyError`, which is intended: there is no implicit localhost fallback.
|
|
75
|
+
|
|
76
|
+
Set explicit socket timeouts on the connection pool, as shown above. The
|
|
77
|
+
runtime performs its automatic-activation Redis work around request handling,
|
|
78
|
+
bounded by a fixed wait; without socket timeouts an unreachable Redis holds
|
|
79
|
+
that entire bound instead of failing fast.
|
|
80
|
+
|
|
81
|
+
## Automatic activation
|
|
82
|
+
|
|
83
|
+
Production deployments activate automatically on their first real request.
|
|
84
|
+
The integration is registered while the application imports, but the Redis
|
|
85
|
+
transition and first Queue send are deferred until the runtime has installed
|
|
86
|
+
that request's OIDC credentials. Builds never enqueue messages.
|
|
87
|
+
|
|
88
|
+
Preview deployments are inactive by default. Opt a project into request-driven
|
|
89
|
+
preview scheduling with:
|
|
90
|
+
|
|
91
|
+
```toml
|
|
92
|
+
[tool.vercel.apscheduler.previews]
|
|
93
|
+
enabled = true
|
|
94
|
+
idle_timeout = "30m"
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Each active Function runtime renews the preview's durable Redis activity
|
|
98
|
+
deadline on incoming requests, throttled to at most once every five minutes
|
|
99
|
+
(or one third of a shorter timeout). This is not a background timer and it
|
|
100
|
+
does not emit periodic Queue messages. If no request renews the deadline:
|
|
101
|
+
|
|
102
|
+
- a queued start or wake becomes stale before it can run;
|
|
103
|
+
- an in-flight wake may finish its current work but cannot publish a
|
|
104
|
+
successor; and
|
|
105
|
+
- the next request creates one new generation and skips occurrences from the
|
|
106
|
+
inactive interval.
|
|
107
|
+
|
|
108
|
+
An explicit `pause()` remains paused across later requests; automatic
|
|
109
|
+
activation never overrides it. Production scheduling has no idle timeout.
|
|
110
|
+
In either environment, a deployment that has never received a request cannot
|
|
111
|
+
start automatically because it has not received request-scoped OIDC
|
|
112
|
+
credentials.
|
|
113
|
+
|
|
114
|
+
## Start, pause, and resume
|
|
115
|
+
|
|
116
|
+
On Vercel, the normal APScheduler lifecycle methods operate the durable Queue
|
|
117
|
+
driver for the deployment executing the call:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
scheduler.start() # idempotently start
|
|
121
|
+
scheduler.pause() # idempotently pause
|
|
122
|
+
scheduler.resume() # idempotently resume
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Use these methods when explicit operational control is needed. Call them from
|
|
126
|
+
an authenticated runtime route or another trusted runtime entrypoint.
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
from fastapi import FastAPI
|
|
130
|
+
|
|
131
|
+
from scheduler import scheduler
|
|
132
|
+
|
|
133
|
+
app = FastAPI()
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
@app.post("/scheduler/start", status_code=202)
|
|
137
|
+
def start_scheduler() -> dict[str, str]:
|
|
138
|
+
scheduler.start()
|
|
139
|
+
return {"state": "running"}
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
@app.post("/scheduler/pause")
|
|
143
|
+
def pause_scheduler() -> dict[str, str]:
|
|
144
|
+
scheduler.pause()
|
|
145
|
+
return {"state": "paused"}
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
@app.post("/scheduler/resume", status_code=202)
|
|
149
|
+
def resume_scheduler() -> dict[str, str]:
|
|
150
|
+
scheduler.resume()
|
|
151
|
+
return {"state": "running"}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
There is no separate control object, start token, or public message-publishing
|
|
155
|
+
API. Each deployment controls only its own scheduler.
|
|
156
|
+
|
|
157
|
+
Off Vercel, these methods retain their normal APScheduler behavior.
|
|
158
|
+
|
|
159
|
+
## Runtime job changes
|
|
160
|
+
|
|
161
|
+
The chain sleeps until the next persisted job is due. It emits no idle
|
|
162
|
+
heartbeat. `add_job()`, `modify_job()`, `reschedule_job()`, `pause_job()`,
|
|
163
|
+
`resume_job()`, and removals update Redis and rearm the one current wake as
|
|
164
|
+
needed.
|
|
165
|
+
|
|
166
|
+
Automatic activation establishes the runtime-mutation boundary before the
|
|
167
|
+
user application handles a production request (or an opted-in preview
|
|
168
|
+
request). In environments without
|
|
169
|
+
automatic activation, call `scheduler.start()` first in each Function
|
|
170
|
+
instance that changes jobs; before that boundary, `add_job()` calls are
|
|
171
|
+
treated as module-level declarations. The call is idempotent:
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
@app.post("/jobs")
|
|
175
|
+
def add_job() -> dict[str, str]:
|
|
176
|
+
scheduler.start()
|
|
177
|
+
scheduler.add_job(
|
|
178
|
+
send_report,
|
|
179
|
+
"date",
|
|
180
|
+
run_date="2026-08-01 09:00:00+00:00",
|
|
181
|
+
id="report-2026-08-01",
|
|
182
|
+
)
|
|
183
|
+
return {"state": "scheduled"}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Job writes and wake rearming happen in one Redis transaction. Raw writes to
|
|
187
|
+
the APScheduler Redis keys bypass that transaction and are unsupported.
|
|
188
|
+
|
|
189
|
+
## Guarantees
|
|
190
|
+
|
|
191
|
+
Redis atomically stores one lifecycle generation and one current wake token
|
|
192
|
+
per scheduler, scoped by environment in production and by deployment in
|
|
193
|
+
previews. This gives the driver the following guarantees:
|
|
194
|
+
|
|
195
|
+
- Concurrent or repeated `start()` calls converge on one start message.
|
|
196
|
+
- Only the current wake token can run and reserve one successor.
|
|
197
|
+
- `pause()` durably fences the current generation.
|
|
198
|
+
- `resume()` creates one new generation, even under concurrent calls.
|
|
199
|
+
- Rapid `pause()`/`resume()` cannot overlap a new generation with an in-flight
|
|
200
|
+
handler from the old generation.
|
|
201
|
+
- Runtime job changes cannot create a second chain.
|
|
202
|
+
- Concurrent job execution and mutation cannot overwrite or resurrect a stale
|
|
203
|
+
job value.
|
|
204
|
+
- A crash between reserving and publishing a successor is repaired by a retry.
|
|
205
|
+
- Occurrences during a pause are skipped on resume instead of replayed in a
|
|
206
|
+
catch-up burst.
|
|
207
|
+
- Production schedules, dynamically added jobs, and the wake chain survive
|
|
208
|
+
promotions: one deployment owns the chain at a time, taking ownership syncs
|
|
209
|
+
the store to that code's declarations (a job deleted from code never runs
|
|
210
|
+
again, a changed trigger takes effect), and a demoted deployment's touches
|
|
211
|
+
are inert.
|
|
212
|
+
- A wake whose queue message died is presumed lost once it is well past due
|
|
213
|
+
with no live owner, and republished by the owner.
|
|
214
|
+
- Concurrent first requests converge on one automatic generation and one
|
|
215
|
+
start identity.
|
|
216
|
+
- Preview idle expiry fences both claims and successor publication.
|
|
217
|
+
- A later preview request creates one new generation; concurrent requests
|
|
218
|
+
converge on that generation.
|
|
219
|
+
|
|
220
|
+
The scheduler's durable identity derives from its `RedisJobStore` `jobs_key`,
|
|
221
|
+
so renaming variables or moving modules never orphans state. Two schedulers
|
|
222
|
+
need distinct `jobs_key` values; the `scheduler_id` option pins an identity
|
|
223
|
+
explicitly.
|
|
224
|
+
|
|
225
|
+
`start()` and job mutation calls are durable after they return successfully.
|
|
226
|
+
If a process dies before returning, an idempotent `start()` repairs any pending
|
|
227
|
+
publication, and repeating an interrupted mutation republishes the pending
|
|
228
|
+
wake even when the retry itself fails on a conflicting job id. With no idle
|
|
229
|
+
heartbeat, an ambiguous failure while publishing the first wake for a dormant
|
|
230
|
+
scheduler is repaired by a later `start()` or mutation call, not by a periodic
|
|
231
|
+
timer. Unless a job chooses its own `misfire_grace_time`, occurrences run when
|
|
232
|
+
their wake arrives, however late; set a finite `misfire_grace_time` on jobs
|
|
233
|
+
that must not run late.
|
|
234
|
+
|
|
235
|
+
These are chain guarantees, not exactly-once job execution. Vercel Queues is
|
|
236
|
+
at-least-once, so a delivery interrupted after a job's side effect may run that
|
|
237
|
+
job again. Scheduled work must still be idempotent. A job already running when
|
|
238
|
+
`pause()` commits may finish, but it cannot extend the paused chain.
|
|
239
|
+
|
|
240
|
+
Redis lifecycle state has no TTL. Losing or evicting it would violate reliable
|
|
241
|
+
pause semantics, so use a durable Redis service rather than an ephemeral
|
|
242
|
+
cache. Redis failures fail closed: lifecycle calls raise and Queue deliveries
|
|
243
|
+
retry without running unfenced work.
|
|
244
|
+
|
|
245
|
+
## Backends
|
|
246
|
+
|
|
247
|
+
Configuring a `RedisJobStore` selects the Redis backend above. Without one,
|
|
248
|
+
the integration runs on the Vercel Runtime Cache instead (explicitly:
|
|
249
|
+
`VERCEL_APSCHEDULER_BACKEND=redis|cache`). The two differ in what they can
|
|
250
|
+
guarantee:
|
|
251
|
+
|
|
252
|
+
| Property | Redis | Runtime Cache |
|
|
253
|
+
| --- | --- | --- |
|
|
254
|
+
| One wake chain, no forks | atomic Lua claims | queue idempotency keys |
|
|
255
|
+
| Job execution | at-least-once | at-least-once, wider duplicate window |
|
|
256
|
+
| Code-declared jobs | durable in Redis | rebuilt from code after eviction |
|
|
257
|
+
| Runtime `add_job()` | durable, revision-checked | best-effort, lost on eviction |
|
|
258
|
+
| `pause()` | durable, fails closed | best-effort flag plus a queue-borne control message |
|
|
259
|
+
|
|
260
|
+
Under `vercel dev` the cache client falls back to per-process memory, which
|
|
261
|
+
makes the cache backend the zero-infrastructure development mode: the
|
|
262
|
+
queue-serving process drives the schedule, and chain progress travels in the
|
|
263
|
+
messages themselves rather than shared state.
|
|
264
|
+
|
|
265
|
+
## v1 restrictions
|
|
266
|
+
|
|
267
|
+
- APScheduler 3.x only.
|
|
268
|
+
- Exactly one Redis-backed job store named `default`.
|
|
269
|
+
- The default inline executor only; custom thread/process executors are
|
|
270
|
+
rejected.
|
|
271
|
+
- Jobs declared in code need explicit stable IDs.
|
|
272
|
+
- When the same ID already exists in Redis, declare it with
|
|
273
|
+
`replace_existing=True`. `scheduled_job()` already enables replacement.
|
|
274
|
+
- Runtime mutation APIs require prior activation in that Function instance,
|
|
275
|
+
either automatically on the request or through `scheduler.start()`.
|
|
276
|
+
- Job execution is at-least-once.
|
|
277
|
+
|
|
278
|
+
See [SCHEDULER.md](SCHEDULER.md) for the state machine and failure model. A
|
|
279
|
+
deployable example is in [examples/cleanup](examples/cleanup).
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
# vercel-apscheduler-bundle
|
|
2
|
+
|
|
3
|
+
This is a version of `vercel-apscheduler` with third-party dependencies bundled. For normal use, install the unbundled `vercel-apscheduler` package instead: https://pypi.org/project/vercel-apscheduler/
|
|
4
|
+
|
|
5
|
+
# Vercel APScheduler integration
|
|
6
|
+
|
|
7
|
+
Run APScheduler 3.x schedules through delayed Vercel Queue messages, with
|
|
8
|
+
Redis as the durable job store and lifecycle coordinator.
|
|
9
|
+
|
|
10
|
+
## Configure the scheduler
|
|
11
|
+
|
|
12
|
+
Use APScheduler's standard Redis job store:
|
|
13
|
+
|
|
14
|
+
```python
|
|
15
|
+
from os import environ
|
|
16
|
+
|
|
17
|
+
from apscheduler.jobstores.redis import RedisJobStore
|
|
18
|
+
from apscheduler.schedulers.blocking import BlockingScheduler
|
|
19
|
+
from redis import ConnectionPool
|
|
20
|
+
|
|
21
|
+
scheduler = BlockingScheduler(
|
|
22
|
+
timezone="UTC",
|
|
23
|
+
jobstores={
|
|
24
|
+
"default": RedisJobStore(
|
|
25
|
+
connection_pool=ConnectionPool.from_url(
|
|
26
|
+
environ["REDIS_URL"],
|
|
27
|
+
socket_connect_timeout=5,
|
|
28
|
+
socket_timeout=5,
|
|
29
|
+
),
|
|
30
|
+
)
|
|
31
|
+
},
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@scheduler.scheduled_job(
|
|
36
|
+
"cron",
|
|
37
|
+
hour=4,
|
|
38
|
+
id="cleanup",
|
|
39
|
+
replace_existing=True,
|
|
40
|
+
)
|
|
41
|
+
def cleanup() -> None: ...
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Declare that object as a Python subscriber:
|
|
45
|
+
|
|
46
|
+
```toml
|
|
47
|
+
[[tool.vercel.subscribers]]
|
|
48
|
+
entrypoint = "scheduler:scheduler"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The Vercel Python builder detects APScheduler before importing the subscriber,
|
|
52
|
+
installs the integration, and extracts its internal Queue subscriptions from
|
|
53
|
+
the same registry used by Celery and Dramatiq. Topic names, consumer groups,
|
|
54
|
+
scheduler IDs, and installation hooks are not application configuration.
|
|
55
|
+
|
|
56
|
+
No Vercel-specific job store is required. v1 requires exactly one job store,
|
|
57
|
+
named `default`, and it must be APScheduler's Redis-backed `RedisJobStore`.
|
|
58
|
+
The integration uses that store's configured Redis client for its internal
|
|
59
|
+
lifecycle coordination. A missing `REDIS_URL` fails the import with a
|
|
60
|
+
`KeyError`, which is intended: there is no implicit localhost fallback.
|
|
61
|
+
|
|
62
|
+
Set explicit socket timeouts on the connection pool, as shown above. The
|
|
63
|
+
runtime performs its automatic-activation Redis work around request handling,
|
|
64
|
+
bounded by a fixed wait; without socket timeouts an unreachable Redis holds
|
|
65
|
+
that entire bound instead of failing fast.
|
|
66
|
+
|
|
67
|
+
## Automatic activation
|
|
68
|
+
|
|
69
|
+
Production deployments activate automatically on their first real request.
|
|
70
|
+
The integration is registered while the application imports, but the Redis
|
|
71
|
+
transition and first Queue send are deferred until the runtime has installed
|
|
72
|
+
that request's OIDC credentials. Builds never enqueue messages.
|
|
73
|
+
|
|
74
|
+
Preview deployments are inactive by default. Opt a project into request-driven
|
|
75
|
+
preview scheduling with:
|
|
76
|
+
|
|
77
|
+
```toml
|
|
78
|
+
[tool.vercel.apscheduler.previews]
|
|
79
|
+
enabled = true
|
|
80
|
+
idle_timeout = "30m"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Each active Function runtime renews the preview's durable Redis activity
|
|
84
|
+
deadline on incoming requests, throttled to at most once every five minutes
|
|
85
|
+
(or one third of a shorter timeout). This is not a background timer and it
|
|
86
|
+
does not emit periodic Queue messages. If no request renews the deadline:
|
|
87
|
+
|
|
88
|
+
- a queued start or wake becomes stale before it can run;
|
|
89
|
+
- an in-flight wake may finish its current work but cannot publish a
|
|
90
|
+
successor; and
|
|
91
|
+
- the next request creates one new generation and skips occurrences from the
|
|
92
|
+
inactive interval.
|
|
93
|
+
|
|
94
|
+
An explicit `pause()` remains paused across later requests; automatic
|
|
95
|
+
activation never overrides it. Production scheduling has no idle timeout.
|
|
96
|
+
In either environment, a deployment that has never received a request cannot
|
|
97
|
+
start automatically because it has not received request-scoped OIDC
|
|
98
|
+
credentials.
|
|
99
|
+
|
|
100
|
+
## Start, pause, and resume
|
|
101
|
+
|
|
102
|
+
On Vercel, the normal APScheduler lifecycle methods operate the durable Queue
|
|
103
|
+
driver for the deployment executing the call:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
scheduler.start() # idempotently start
|
|
107
|
+
scheduler.pause() # idempotently pause
|
|
108
|
+
scheduler.resume() # idempotently resume
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Use these methods when explicit operational control is needed. Call them from
|
|
112
|
+
an authenticated runtime route or another trusted runtime entrypoint.
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
from fastapi import FastAPI
|
|
116
|
+
|
|
117
|
+
from scheduler import scheduler
|
|
118
|
+
|
|
119
|
+
app = FastAPI()
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@app.post("/scheduler/start", status_code=202)
|
|
123
|
+
def start_scheduler() -> dict[str, str]:
|
|
124
|
+
scheduler.start()
|
|
125
|
+
return {"state": "running"}
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@app.post("/scheduler/pause")
|
|
129
|
+
def pause_scheduler() -> dict[str, str]:
|
|
130
|
+
scheduler.pause()
|
|
131
|
+
return {"state": "paused"}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@app.post("/scheduler/resume", status_code=202)
|
|
135
|
+
def resume_scheduler() -> dict[str, str]:
|
|
136
|
+
scheduler.resume()
|
|
137
|
+
return {"state": "running"}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
There is no separate control object, start token, or public message-publishing
|
|
141
|
+
API. Each deployment controls only its own scheduler.
|
|
142
|
+
|
|
143
|
+
Off Vercel, these methods retain their normal APScheduler behavior.
|
|
144
|
+
|
|
145
|
+
## Runtime job changes
|
|
146
|
+
|
|
147
|
+
The chain sleeps until the next persisted job is due. It emits no idle
|
|
148
|
+
heartbeat. `add_job()`, `modify_job()`, `reschedule_job()`, `pause_job()`,
|
|
149
|
+
`resume_job()`, and removals update Redis and rearm the one current wake as
|
|
150
|
+
needed.
|
|
151
|
+
|
|
152
|
+
Automatic activation establishes the runtime-mutation boundary before the
|
|
153
|
+
user application handles a production request (or an opted-in preview
|
|
154
|
+
request). In environments without
|
|
155
|
+
automatic activation, call `scheduler.start()` first in each Function
|
|
156
|
+
instance that changes jobs; before that boundary, `add_job()` calls are
|
|
157
|
+
treated as module-level declarations. The call is idempotent:
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
@app.post("/jobs")
|
|
161
|
+
def add_job() -> dict[str, str]:
|
|
162
|
+
scheduler.start()
|
|
163
|
+
scheduler.add_job(
|
|
164
|
+
send_report,
|
|
165
|
+
"date",
|
|
166
|
+
run_date="2026-08-01 09:00:00+00:00",
|
|
167
|
+
id="report-2026-08-01",
|
|
168
|
+
)
|
|
169
|
+
return {"state": "scheduled"}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Job writes and wake rearming happen in one Redis transaction. Raw writes to
|
|
173
|
+
the APScheduler Redis keys bypass that transaction and are unsupported.
|
|
174
|
+
|
|
175
|
+
## Guarantees
|
|
176
|
+
|
|
177
|
+
Redis atomically stores one lifecycle generation and one current wake token
|
|
178
|
+
per scheduler, scoped by environment in production and by deployment in
|
|
179
|
+
previews. This gives the driver the following guarantees:
|
|
180
|
+
|
|
181
|
+
- Concurrent or repeated `start()` calls converge on one start message.
|
|
182
|
+
- Only the current wake token can run and reserve one successor.
|
|
183
|
+
- `pause()` durably fences the current generation.
|
|
184
|
+
- `resume()` creates one new generation, even under concurrent calls.
|
|
185
|
+
- Rapid `pause()`/`resume()` cannot overlap a new generation with an in-flight
|
|
186
|
+
handler from the old generation.
|
|
187
|
+
- Runtime job changes cannot create a second chain.
|
|
188
|
+
- Concurrent job execution and mutation cannot overwrite or resurrect a stale
|
|
189
|
+
job value.
|
|
190
|
+
- A crash between reserving and publishing a successor is repaired by a retry.
|
|
191
|
+
- Occurrences during a pause are skipped on resume instead of replayed in a
|
|
192
|
+
catch-up burst.
|
|
193
|
+
- Production schedules, dynamically added jobs, and the wake chain survive
|
|
194
|
+
promotions: one deployment owns the chain at a time, taking ownership syncs
|
|
195
|
+
the store to that code's declarations (a job deleted from code never runs
|
|
196
|
+
again, a changed trigger takes effect), and a demoted deployment's touches
|
|
197
|
+
are inert.
|
|
198
|
+
- A wake whose queue message died is presumed lost once it is well past due
|
|
199
|
+
with no live owner, and republished by the owner.
|
|
200
|
+
- Concurrent first requests converge on one automatic generation and one
|
|
201
|
+
start identity.
|
|
202
|
+
- Preview idle expiry fences both claims and successor publication.
|
|
203
|
+
- A later preview request creates one new generation; concurrent requests
|
|
204
|
+
converge on that generation.
|
|
205
|
+
|
|
206
|
+
The scheduler's durable identity derives from its `RedisJobStore` `jobs_key`,
|
|
207
|
+
so renaming variables or moving modules never orphans state. Two schedulers
|
|
208
|
+
need distinct `jobs_key` values; the `scheduler_id` option pins an identity
|
|
209
|
+
explicitly.
|
|
210
|
+
|
|
211
|
+
`start()` and job mutation calls are durable after they return successfully.
|
|
212
|
+
If a process dies before returning, an idempotent `start()` repairs any pending
|
|
213
|
+
publication, and repeating an interrupted mutation republishes the pending
|
|
214
|
+
wake even when the retry itself fails on a conflicting job id. With no idle
|
|
215
|
+
heartbeat, an ambiguous failure while publishing the first wake for a dormant
|
|
216
|
+
scheduler is repaired by a later `start()` or mutation call, not by a periodic
|
|
217
|
+
timer. Unless a job chooses its own `misfire_grace_time`, occurrences run when
|
|
218
|
+
their wake arrives, however late; set a finite `misfire_grace_time` on jobs
|
|
219
|
+
that must not run late.
|
|
220
|
+
|
|
221
|
+
These are chain guarantees, not exactly-once job execution. Vercel Queues is
|
|
222
|
+
at-least-once, so a delivery interrupted after a job's side effect may run that
|
|
223
|
+
job again. Scheduled work must still be idempotent. A job already running when
|
|
224
|
+
`pause()` commits may finish, but it cannot extend the paused chain.
|
|
225
|
+
|
|
226
|
+
Redis lifecycle state has no TTL. Losing or evicting it would violate reliable
|
|
227
|
+
pause semantics, so use a durable Redis service rather than an ephemeral
|
|
228
|
+
cache. Redis failures fail closed: lifecycle calls raise and Queue deliveries
|
|
229
|
+
retry without running unfenced work.
|
|
230
|
+
|
|
231
|
+
## Backends
|
|
232
|
+
|
|
233
|
+
Configuring a `RedisJobStore` selects the Redis backend above. Without one,
|
|
234
|
+
the integration runs on the Vercel Runtime Cache instead (explicitly:
|
|
235
|
+
`VERCEL_APSCHEDULER_BACKEND=redis|cache`). The two differ in what they can
|
|
236
|
+
guarantee:
|
|
237
|
+
|
|
238
|
+
| Property | Redis | Runtime Cache |
|
|
239
|
+
| --- | --- | --- |
|
|
240
|
+
| One wake chain, no forks | atomic Lua claims | queue idempotency keys |
|
|
241
|
+
| Job execution | at-least-once | at-least-once, wider duplicate window |
|
|
242
|
+
| Code-declared jobs | durable in Redis | rebuilt from code after eviction |
|
|
243
|
+
| Runtime `add_job()` | durable, revision-checked | best-effort, lost on eviction |
|
|
244
|
+
| `pause()` | durable, fails closed | best-effort flag plus a queue-borne control message |
|
|
245
|
+
|
|
246
|
+
Under `vercel dev` the cache client falls back to per-process memory, which
|
|
247
|
+
makes the cache backend the zero-infrastructure development mode: the
|
|
248
|
+
queue-serving process drives the schedule, and chain progress travels in the
|
|
249
|
+
messages themselves rather than shared state.
|
|
250
|
+
|
|
251
|
+
## v1 restrictions
|
|
252
|
+
|
|
253
|
+
- APScheduler 3.x only.
|
|
254
|
+
- Exactly one Redis-backed job store named `default`.
|
|
255
|
+
- The default inline executor only; custom thread/process executors are
|
|
256
|
+
rejected.
|
|
257
|
+
- Jobs declared in code need explicit stable IDs.
|
|
258
|
+
- When the same ID already exists in Redis, declare it with
|
|
259
|
+
`replace_existing=True`. `scheduled_job()` already enables replacement.
|
|
260
|
+
- Runtime mutation APIs require prior activation in that Function instance,
|
|
261
|
+
either automatically on the request or through `scheduler.start()`.
|
|
262
|
+
- Job execution is at-least-once.
|
|
263
|
+
|
|
264
|
+
See [SCHEDULER.md](SCHEDULER.md) for the state machine and failure model. A
|
|
265
|
+
deployable example is in [examples/cleanup](examples/cleanup).
|