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.
Files changed (33) hide show
  1. vercel_apscheduler_bundle-0.1.0/LICENSE +21 -0
  2. vercel_apscheduler_bundle-0.1.0/PKG-INFO +279 -0
  3. vercel_apscheduler_bundle-0.1.0/README.md +265 -0
  4. vercel_apscheduler_bundle-0.1.0/SCHEDULER.md +482 -0
  5. vercel_apscheduler_bundle-0.1.0/examples/cleanup/README.md +49 -0
  6. vercel_apscheduler_bundle-0.1.0/examples/cleanup/main.py +47 -0
  7. vercel_apscheduler_bundle-0.1.0/examples/cleanup/pyproject.toml +19 -0
  8. vercel_apscheduler_bundle-0.1.0/examples/cleanup/scheduler.py +48 -0
  9. vercel_apscheduler_bundle-0.1.0/examples/cleanup/vercel.json +3 -0
  10. vercel_apscheduler_bundle-0.1.0/pyproject.toml +146 -0
  11. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/__init__.py +15 -0
  12. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_adapter.py +1375 -0
  13. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_automatic.py +249 -0
  14. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/__init__.py +50 -0
  15. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/_protocols.py +197 -0
  16. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/__init__.py +122 -0
  17. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/_doc.py +29 -0
  18. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/_driver.py +586 -0
  19. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/cache/_jobstore.py +375 -0
  20. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/redis/__init__.py +99 -0
  21. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/redis/_driver.py +983 -0
  22. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_backends/redis/_jobstore.py +477 -0
  23. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_control.py +88 -0
  24. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_executor.py +140 -0
  25. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_imports.py +53 -0
  26. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_options.py +296 -0
  27. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_payload.py +132 -0
  28. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_subscriber.py +223 -0
  29. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_time.py +51 -0
  30. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_types.py +116 -0
  31. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/_vendor/__init__.py +1 -0
  32. vercel_apscheduler_bundle-0.1.0/vercel/integrations/apscheduler/py.typed +1 -0
  33. 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).