vercel-apscheduler 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-0.1.0/.gitignore +130 -0
  2. vercel_apscheduler-0.1.0/LICENSE +21 -0
  3. vercel_apscheduler-0.1.0/PKG-INFO +274 -0
  4. vercel_apscheduler-0.1.0/README.md +261 -0
  5. vercel_apscheduler-0.1.0/SCHEDULER.md +482 -0
  6. vercel_apscheduler-0.1.0/examples/cleanup/README.md +49 -0
  7. vercel_apscheduler-0.1.0/examples/cleanup/main.py +47 -0
  8. vercel_apscheduler-0.1.0/examples/cleanup/pyproject.toml +19 -0
  9. vercel_apscheduler-0.1.0/examples/cleanup/scheduler.py +48 -0
  10. vercel_apscheduler-0.1.0/examples/cleanup/vercel.json +3 -0
  11. vercel_apscheduler-0.1.0/pyproject.toml +124 -0
  12. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/__init__.py +15 -0
  13. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_adapter.py +1375 -0
  14. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_automatic.py +249 -0
  15. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/__init__.py +50 -0
  16. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/_protocols.py +197 -0
  17. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/cache/__init__.py +122 -0
  18. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/cache/_doc.py +29 -0
  19. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/cache/_driver.py +586 -0
  20. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/cache/_jobstore.py +375 -0
  21. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/redis/__init__.py +99 -0
  22. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/redis/_driver.py +983 -0
  23. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_backends/redis/_jobstore.py +477 -0
  24. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_control.py +88 -0
  25. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_executor.py +140 -0
  26. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_imports.py +53 -0
  27. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_options.py +296 -0
  28. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_payload.py +132 -0
  29. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_subscriber.py +223 -0
  30. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_time.py +51 -0
  31. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/_types.py +116 -0
  32. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/py.typed +1 -0
  33. vercel_apscheduler-0.1.0/vercel/integrations/apscheduler/version.py +1 -0
@@ -0,0 +1,130 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+
5
+ # C extensions
6
+ *.so
7
+
8
+ # Distribution / packaging
9
+ .Python
10
+ build/
11
+ develop-eggs/
12
+ dist/
13
+ downloads/
14
+ eggs/
15
+ .eggs/
16
+ lib/
17
+ lib64/
18
+ parts/
19
+ sdist/
20
+ var/
21
+ wheels/
22
+ share/python-wheels/
23
+ *.egg-info/
24
+ .installed.cfg
25
+ *.egg
26
+ MANIFEST
27
+
28
+ # PyInstallerhave
29
+ *.manifest
30
+ *.spec
31
+
32
+ # Installer logs
33
+ pip-log.txt
34
+ pip-delete-this-directory.txt
35
+
36
+ # Unit test / coverage reports
37
+ .benchmarks/
38
+ htmlcov/
39
+ .tox/
40
+ .nox/
41
+ .coverage
42
+ .coverage.*
43
+ .cache
44
+ nosetests.xml
45
+ coverage.xml
46
+ *.cover
47
+ *.py,cover
48
+ .hypothesis/
49
+ .pytest_cache/
50
+ .ruff_cache/
51
+
52
+ # Translations
53
+ *.mo
54
+ *.pot
55
+
56
+ # Scrapy
57
+ .scrapy
58
+
59
+ # Sphinx documentation
60
+ docs/_build/
61
+
62
+ # PyBuilder
63
+ target/
64
+
65
+ # Jupyter Notebook
66
+ .ipynb_checkpoints
67
+
68
+ # IPython
69
+ profile_default/
70
+ ipython_config.py
71
+
72
+ # pyenv
73
+ .python-version
74
+
75
+ # pipenv
76
+ Pipfile.lock
77
+
78
+ # poetry
79
+ poetry.lock
80
+
81
+ # PDM
82
+ pdm.lock
83
+ .pdm.toml
84
+
85
+ # Hatch
86
+ .hatch/
87
+
88
+ # pyright/mypy
89
+ .mypy_cache/
90
+ .dmypy.json
91
+ dmypy.json
92
+
93
+ # pyre
94
+ .pyre/
95
+
96
+ # pytype
97
+ .pytype/
98
+
99
+ # Caches
100
+ __pypackages__/
101
+
102
+ # Editor/project files
103
+ .DS_Store
104
+ .idea/
105
+ .vscode/
106
+ .zed/
107
+ *.swp
108
+ *.swo
109
+
110
+ # Virtual environments
111
+ .env
112
+ .venv
113
+ .venv.*
114
+ env/
115
+ venv/
116
+ **/.env
117
+ **/.venv
118
+ **/.venv.*
119
+ **/env/
120
+ **/venv/
121
+ ENV/
122
+ env.bak/
123
+ venv.bak/
124
+
125
+ # dotenv anywhere
126
+ **/.env
127
+ **/.env.*
128
+ **/*.env
129
+
130
+ .claude
@@ -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,274 @@
1
+ Metadata-Version: 2.4
2
+ Name: vercel-apscheduler
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>=0.7.1
11
+ Requires-Dist: vercel-queue>=0.6.0
12
+ Description-Content-Type: text/markdown
13
+
14
+ # Vercel APScheduler integration
15
+
16
+ Run APScheduler 3.x schedules through delayed Vercel Queue messages, with
17
+ Redis as the durable job store and lifecycle coordinator.
18
+
19
+ ## Configure the scheduler
20
+
21
+ Use APScheduler's standard Redis job store:
22
+
23
+ ```python
24
+ from os import environ
25
+
26
+ from apscheduler.jobstores.redis import RedisJobStore
27
+ from apscheduler.schedulers.blocking import BlockingScheduler
28
+ from redis import ConnectionPool
29
+
30
+ scheduler = BlockingScheduler(
31
+ timezone="UTC",
32
+ jobstores={
33
+ "default": RedisJobStore(
34
+ connection_pool=ConnectionPool.from_url(
35
+ environ["REDIS_URL"],
36
+ socket_connect_timeout=5,
37
+ socket_timeout=5,
38
+ ),
39
+ )
40
+ },
41
+ )
42
+
43
+
44
+ @scheduler.scheduled_job(
45
+ "cron",
46
+ hour=4,
47
+ id="cleanup",
48
+ replace_existing=True,
49
+ )
50
+ def cleanup() -> None: ...
51
+ ```
52
+
53
+ Declare that object as a Python subscriber:
54
+
55
+ ```toml
56
+ [[tool.vercel.subscribers]]
57
+ entrypoint = "scheduler:scheduler"
58
+ ```
59
+
60
+ The Vercel Python builder detects APScheduler before importing the subscriber,
61
+ installs the integration, and extracts its internal Queue subscriptions from
62
+ the same registry used by Celery and Dramatiq. Topic names, consumer groups,
63
+ scheduler IDs, and installation hooks are not application configuration.
64
+
65
+ No Vercel-specific job store is required. v1 requires exactly one job store,
66
+ named `default`, and it must be APScheduler's Redis-backed `RedisJobStore`.
67
+ The integration uses that store's configured Redis client for its internal
68
+ lifecycle coordination. A missing `REDIS_URL` fails the import with a
69
+ `KeyError`, which is intended: there is no implicit localhost fallback.
70
+
71
+ Set explicit socket timeouts on the connection pool, as shown above. The
72
+ runtime performs its automatic-activation Redis work around request handling,
73
+ bounded by a fixed wait; without socket timeouts an unreachable Redis holds
74
+ that entire bound instead of failing fast.
75
+
76
+ ## Automatic activation
77
+
78
+ Production deployments activate automatically on their first real request.
79
+ The integration is registered while the application imports, but the Redis
80
+ transition and first Queue send are deferred until the runtime has installed
81
+ that request's OIDC credentials. Builds never enqueue messages.
82
+
83
+ Preview deployments are inactive by default. Opt a project into request-driven
84
+ preview scheduling with:
85
+
86
+ ```toml
87
+ [tool.vercel.apscheduler.previews]
88
+ enabled = true
89
+ idle_timeout = "30m"
90
+ ```
91
+
92
+ Each active Function runtime renews the preview's durable Redis activity
93
+ deadline on incoming requests, throttled to at most once every five minutes
94
+ (or one third of a shorter timeout). This is not a background timer and it
95
+ does not emit periodic Queue messages. If no request renews the deadline:
96
+
97
+ - a queued start or wake becomes stale before it can run;
98
+ - an in-flight wake may finish its current work but cannot publish a
99
+ successor; and
100
+ - the next request creates one new generation and skips occurrences from the
101
+ inactive interval.
102
+
103
+ An explicit `pause()` remains paused across later requests; automatic
104
+ activation never overrides it. Production scheduling has no idle timeout.
105
+ In either environment, a deployment that has never received a request cannot
106
+ start automatically because it has not received request-scoped OIDC
107
+ credentials.
108
+
109
+ ## Start, pause, and resume
110
+
111
+ On Vercel, the normal APScheduler lifecycle methods operate the durable Queue
112
+ driver for the deployment executing the call:
113
+
114
+ ```python
115
+ scheduler.start() # idempotently start
116
+ scheduler.pause() # idempotently pause
117
+ scheduler.resume() # idempotently resume
118
+ ```
119
+
120
+ Use these methods when explicit operational control is needed. Call them from
121
+ an authenticated runtime route or another trusted runtime entrypoint.
122
+
123
+ ```python
124
+ from fastapi import FastAPI
125
+
126
+ from scheduler import scheduler
127
+
128
+ app = FastAPI()
129
+
130
+
131
+ @app.post("/scheduler/start", status_code=202)
132
+ def start_scheduler() -> dict[str, str]:
133
+ scheduler.start()
134
+ return {"state": "running"}
135
+
136
+
137
+ @app.post("/scheduler/pause")
138
+ def pause_scheduler() -> dict[str, str]:
139
+ scheduler.pause()
140
+ return {"state": "paused"}
141
+
142
+
143
+ @app.post("/scheduler/resume", status_code=202)
144
+ def resume_scheduler() -> dict[str, str]:
145
+ scheduler.resume()
146
+ return {"state": "running"}
147
+ ```
148
+
149
+ There is no separate control object, start token, or public message-publishing
150
+ API. Each deployment controls only its own scheduler.
151
+
152
+ Off Vercel, these methods retain their normal APScheduler behavior.
153
+
154
+ ## Runtime job changes
155
+
156
+ The chain sleeps until the next persisted job is due. It emits no idle
157
+ heartbeat. `add_job()`, `modify_job()`, `reschedule_job()`, `pause_job()`,
158
+ `resume_job()`, and removals update Redis and rearm the one current wake as
159
+ needed.
160
+
161
+ Automatic activation establishes the runtime-mutation boundary before the
162
+ user application handles a production request (or an opted-in preview
163
+ request). In environments without
164
+ automatic activation, call `scheduler.start()` first in each Function
165
+ instance that changes jobs; before that boundary, `add_job()` calls are
166
+ treated as module-level declarations. The call is idempotent:
167
+
168
+ ```python
169
+ @app.post("/jobs")
170
+ def add_job() -> dict[str, str]:
171
+ scheduler.start()
172
+ scheduler.add_job(
173
+ send_report,
174
+ "date",
175
+ run_date="2026-08-01 09:00:00+00:00",
176
+ id="report-2026-08-01",
177
+ )
178
+ return {"state": "scheduled"}
179
+ ```
180
+
181
+ Job writes and wake rearming happen in one Redis transaction. Raw writes to
182
+ the APScheduler Redis keys bypass that transaction and are unsupported.
183
+
184
+ ## Guarantees
185
+
186
+ Redis atomically stores one lifecycle generation and one current wake token
187
+ per scheduler, scoped by environment in production and by deployment in
188
+ previews. This gives the driver the following guarantees:
189
+
190
+ - Concurrent or repeated `start()` calls converge on one start message.
191
+ - Only the current wake token can run and reserve one successor.
192
+ - `pause()` durably fences the current generation.
193
+ - `resume()` creates one new generation, even under concurrent calls.
194
+ - Rapid `pause()`/`resume()` cannot overlap a new generation with an in-flight
195
+ handler from the old generation.
196
+ - Runtime job changes cannot create a second chain.
197
+ - Concurrent job execution and mutation cannot overwrite or resurrect a stale
198
+ job value.
199
+ - A crash between reserving and publishing a successor is repaired by a retry.
200
+ - Occurrences during a pause are skipped on resume instead of replayed in a
201
+ catch-up burst.
202
+ - Production schedules, dynamically added jobs, and the wake chain survive
203
+ promotions: one deployment owns the chain at a time, taking ownership syncs
204
+ the store to that code's declarations (a job deleted from code never runs
205
+ again, a changed trigger takes effect), and a demoted deployment's touches
206
+ are inert.
207
+ - A wake whose queue message died is presumed lost once it is well past due
208
+ with no live owner, and republished by the owner.
209
+ - Concurrent first requests converge on one automatic generation and one
210
+ start identity.
211
+ - Preview idle expiry fences both claims and successor publication.
212
+ - A later preview request creates one new generation; concurrent requests
213
+ converge on that generation.
214
+
215
+ The scheduler's durable identity derives from its `RedisJobStore` `jobs_key`,
216
+ so renaming variables or moving modules never orphans state. Two schedulers
217
+ need distinct `jobs_key` values; the `scheduler_id` option pins an identity
218
+ explicitly.
219
+
220
+ `start()` and job mutation calls are durable after they return successfully.
221
+ If a process dies before returning, an idempotent `start()` repairs any pending
222
+ publication, and repeating an interrupted mutation republishes the pending
223
+ wake even when the retry itself fails on a conflicting job id. With no idle
224
+ heartbeat, an ambiguous failure while publishing the first wake for a dormant
225
+ scheduler is repaired by a later `start()` or mutation call, not by a periodic
226
+ timer. Unless a job chooses its own `misfire_grace_time`, occurrences run when
227
+ their wake arrives, however late; set a finite `misfire_grace_time` on jobs
228
+ that must not run late.
229
+
230
+ These are chain guarantees, not exactly-once job execution. Vercel Queues is
231
+ at-least-once, so a delivery interrupted after a job's side effect may run that
232
+ job again. Scheduled work must still be idempotent. A job already running when
233
+ `pause()` commits may finish, but it cannot extend the paused chain.
234
+
235
+ Redis lifecycle state has no TTL. Losing or evicting it would violate reliable
236
+ pause semantics, so use a durable Redis service rather than an ephemeral
237
+ cache. Redis failures fail closed: lifecycle calls raise and Queue deliveries
238
+ retry without running unfenced work.
239
+
240
+ ## Backends
241
+
242
+ Configuring a `RedisJobStore` selects the Redis backend above. Without one,
243
+ the integration runs on the Vercel Runtime Cache instead (explicitly:
244
+ `VERCEL_APSCHEDULER_BACKEND=redis|cache`). The two differ in what they can
245
+ guarantee:
246
+
247
+ | Property | Redis | Runtime Cache |
248
+ | --- | --- | --- |
249
+ | One wake chain, no forks | atomic Lua claims | queue idempotency keys |
250
+ | Job execution | at-least-once | at-least-once, wider duplicate window |
251
+ | Code-declared jobs | durable in Redis | rebuilt from code after eviction |
252
+ | Runtime `add_job()` | durable, revision-checked | best-effort, lost on eviction |
253
+ | `pause()` | durable, fails closed | best-effort flag plus a queue-borne control message |
254
+
255
+ Under `vercel dev` the cache client falls back to per-process memory, which
256
+ makes the cache backend the zero-infrastructure development mode: the
257
+ queue-serving process drives the schedule, and chain progress travels in the
258
+ messages themselves rather than shared state.
259
+
260
+ ## v1 restrictions
261
+
262
+ - APScheduler 3.x only.
263
+ - Exactly one Redis-backed job store named `default`.
264
+ - The default inline executor only; custom thread/process executors are
265
+ rejected.
266
+ - Jobs declared in code need explicit stable IDs.
267
+ - When the same ID already exists in Redis, declare it with
268
+ `replace_existing=True`. `scheduled_job()` already enables replacement.
269
+ - Runtime mutation APIs require prior activation in that Function instance,
270
+ either automatically on the request or through `scheduler.start()`.
271
+ - Job execution is at-least-once.
272
+
273
+ See [SCHEDULER.md](SCHEDULER.md) for the state machine and failure model. A
274
+ deployable example is in [examples/cleanup](examples/cleanup).
@@ -0,0 +1,261 @@
1
+ # Vercel APScheduler integration
2
+
3
+ Run APScheduler 3.x schedules through delayed Vercel Queue messages, with
4
+ Redis as the durable job store and lifecycle coordinator.
5
+
6
+ ## Configure the scheduler
7
+
8
+ Use APScheduler's standard Redis job store:
9
+
10
+ ```python
11
+ from os import environ
12
+
13
+ from apscheduler.jobstores.redis import RedisJobStore
14
+ from apscheduler.schedulers.blocking import BlockingScheduler
15
+ from redis import ConnectionPool
16
+
17
+ scheduler = BlockingScheduler(
18
+ timezone="UTC",
19
+ jobstores={
20
+ "default": RedisJobStore(
21
+ connection_pool=ConnectionPool.from_url(
22
+ environ["REDIS_URL"],
23
+ socket_connect_timeout=5,
24
+ socket_timeout=5,
25
+ ),
26
+ )
27
+ },
28
+ )
29
+
30
+
31
+ @scheduler.scheduled_job(
32
+ "cron",
33
+ hour=4,
34
+ id="cleanup",
35
+ replace_existing=True,
36
+ )
37
+ def cleanup() -> None: ...
38
+ ```
39
+
40
+ Declare that object as a Python subscriber:
41
+
42
+ ```toml
43
+ [[tool.vercel.subscribers]]
44
+ entrypoint = "scheduler:scheduler"
45
+ ```
46
+
47
+ The Vercel Python builder detects APScheduler before importing the subscriber,
48
+ installs the integration, and extracts its internal Queue subscriptions from
49
+ the same registry used by Celery and Dramatiq. Topic names, consumer groups,
50
+ scheduler IDs, and installation hooks are not application configuration.
51
+
52
+ No Vercel-specific job store is required. v1 requires exactly one job store,
53
+ named `default`, and it must be APScheduler's Redis-backed `RedisJobStore`.
54
+ The integration uses that store's configured Redis client for its internal
55
+ lifecycle coordination. A missing `REDIS_URL` fails the import with a
56
+ `KeyError`, which is intended: there is no implicit localhost fallback.
57
+
58
+ Set explicit socket timeouts on the connection pool, as shown above. The
59
+ runtime performs its automatic-activation Redis work around request handling,
60
+ bounded by a fixed wait; without socket timeouts an unreachable Redis holds
61
+ that entire bound instead of failing fast.
62
+
63
+ ## Automatic activation
64
+
65
+ Production deployments activate automatically on their first real request.
66
+ The integration is registered while the application imports, but the Redis
67
+ transition and first Queue send are deferred until the runtime has installed
68
+ that request's OIDC credentials. Builds never enqueue messages.
69
+
70
+ Preview deployments are inactive by default. Opt a project into request-driven
71
+ preview scheduling with:
72
+
73
+ ```toml
74
+ [tool.vercel.apscheduler.previews]
75
+ enabled = true
76
+ idle_timeout = "30m"
77
+ ```
78
+
79
+ Each active Function runtime renews the preview's durable Redis activity
80
+ deadline on incoming requests, throttled to at most once every five minutes
81
+ (or one third of a shorter timeout). This is not a background timer and it
82
+ does not emit periodic Queue messages. If no request renews the deadline:
83
+
84
+ - a queued start or wake becomes stale before it can run;
85
+ - an in-flight wake may finish its current work but cannot publish a
86
+ successor; and
87
+ - the next request creates one new generation and skips occurrences from the
88
+ inactive interval.
89
+
90
+ An explicit `pause()` remains paused across later requests; automatic
91
+ activation never overrides it. Production scheduling has no idle timeout.
92
+ In either environment, a deployment that has never received a request cannot
93
+ start automatically because it has not received request-scoped OIDC
94
+ credentials.
95
+
96
+ ## Start, pause, and resume
97
+
98
+ On Vercel, the normal APScheduler lifecycle methods operate the durable Queue
99
+ driver for the deployment executing the call:
100
+
101
+ ```python
102
+ scheduler.start() # idempotently start
103
+ scheduler.pause() # idempotently pause
104
+ scheduler.resume() # idempotently resume
105
+ ```
106
+
107
+ Use these methods when explicit operational control is needed. Call them from
108
+ an authenticated runtime route or another trusted runtime entrypoint.
109
+
110
+ ```python
111
+ from fastapi import FastAPI
112
+
113
+ from scheduler import scheduler
114
+
115
+ app = FastAPI()
116
+
117
+
118
+ @app.post("/scheduler/start", status_code=202)
119
+ def start_scheduler() -> dict[str, str]:
120
+ scheduler.start()
121
+ return {"state": "running"}
122
+
123
+
124
+ @app.post("/scheduler/pause")
125
+ def pause_scheduler() -> dict[str, str]:
126
+ scheduler.pause()
127
+ return {"state": "paused"}
128
+
129
+
130
+ @app.post("/scheduler/resume", status_code=202)
131
+ def resume_scheduler() -> dict[str, str]:
132
+ scheduler.resume()
133
+ return {"state": "running"}
134
+ ```
135
+
136
+ There is no separate control object, start token, or public message-publishing
137
+ API. Each deployment controls only its own scheduler.
138
+
139
+ Off Vercel, these methods retain their normal APScheduler behavior.
140
+
141
+ ## Runtime job changes
142
+
143
+ The chain sleeps until the next persisted job is due. It emits no idle
144
+ heartbeat. `add_job()`, `modify_job()`, `reschedule_job()`, `pause_job()`,
145
+ `resume_job()`, and removals update Redis and rearm the one current wake as
146
+ needed.
147
+
148
+ Automatic activation establishes the runtime-mutation boundary before the
149
+ user application handles a production request (or an opted-in preview
150
+ request). In environments without
151
+ automatic activation, call `scheduler.start()` first in each Function
152
+ instance that changes jobs; before that boundary, `add_job()` calls are
153
+ treated as module-level declarations. The call is idempotent:
154
+
155
+ ```python
156
+ @app.post("/jobs")
157
+ def add_job() -> dict[str, str]:
158
+ scheduler.start()
159
+ scheduler.add_job(
160
+ send_report,
161
+ "date",
162
+ run_date="2026-08-01 09:00:00+00:00",
163
+ id="report-2026-08-01",
164
+ )
165
+ return {"state": "scheduled"}
166
+ ```
167
+
168
+ Job writes and wake rearming happen in one Redis transaction. Raw writes to
169
+ the APScheduler Redis keys bypass that transaction and are unsupported.
170
+
171
+ ## Guarantees
172
+
173
+ Redis atomically stores one lifecycle generation and one current wake token
174
+ per scheduler, scoped by environment in production and by deployment in
175
+ previews. This gives the driver the following guarantees:
176
+
177
+ - Concurrent or repeated `start()` calls converge on one start message.
178
+ - Only the current wake token can run and reserve one successor.
179
+ - `pause()` durably fences the current generation.
180
+ - `resume()` creates one new generation, even under concurrent calls.
181
+ - Rapid `pause()`/`resume()` cannot overlap a new generation with an in-flight
182
+ handler from the old generation.
183
+ - Runtime job changes cannot create a second chain.
184
+ - Concurrent job execution and mutation cannot overwrite or resurrect a stale
185
+ job value.
186
+ - A crash between reserving and publishing a successor is repaired by a retry.
187
+ - Occurrences during a pause are skipped on resume instead of replayed in a
188
+ catch-up burst.
189
+ - Production schedules, dynamically added jobs, and the wake chain survive
190
+ promotions: one deployment owns the chain at a time, taking ownership syncs
191
+ the store to that code's declarations (a job deleted from code never runs
192
+ again, a changed trigger takes effect), and a demoted deployment's touches
193
+ are inert.
194
+ - A wake whose queue message died is presumed lost once it is well past due
195
+ with no live owner, and republished by the owner.
196
+ - Concurrent first requests converge on one automatic generation and one
197
+ start identity.
198
+ - Preview idle expiry fences both claims and successor publication.
199
+ - A later preview request creates one new generation; concurrent requests
200
+ converge on that generation.
201
+
202
+ The scheduler's durable identity derives from its `RedisJobStore` `jobs_key`,
203
+ so renaming variables or moving modules never orphans state. Two schedulers
204
+ need distinct `jobs_key` values; the `scheduler_id` option pins an identity
205
+ explicitly.
206
+
207
+ `start()` and job mutation calls are durable after they return successfully.
208
+ If a process dies before returning, an idempotent `start()` repairs any pending
209
+ publication, and repeating an interrupted mutation republishes the pending
210
+ wake even when the retry itself fails on a conflicting job id. With no idle
211
+ heartbeat, an ambiguous failure while publishing the first wake for a dormant
212
+ scheduler is repaired by a later `start()` or mutation call, not by a periodic
213
+ timer. Unless a job chooses its own `misfire_grace_time`, occurrences run when
214
+ their wake arrives, however late; set a finite `misfire_grace_time` on jobs
215
+ that must not run late.
216
+
217
+ These are chain guarantees, not exactly-once job execution. Vercel Queues is
218
+ at-least-once, so a delivery interrupted after a job's side effect may run that
219
+ job again. Scheduled work must still be idempotent. A job already running when
220
+ `pause()` commits may finish, but it cannot extend the paused chain.
221
+
222
+ Redis lifecycle state has no TTL. Losing or evicting it would violate reliable
223
+ pause semantics, so use a durable Redis service rather than an ephemeral
224
+ cache. Redis failures fail closed: lifecycle calls raise and Queue deliveries
225
+ retry without running unfenced work.
226
+
227
+ ## Backends
228
+
229
+ Configuring a `RedisJobStore` selects the Redis backend above. Without one,
230
+ the integration runs on the Vercel Runtime Cache instead (explicitly:
231
+ `VERCEL_APSCHEDULER_BACKEND=redis|cache`). The two differ in what they can
232
+ guarantee:
233
+
234
+ | Property | Redis | Runtime Cache |
235
+ | --- | --- | --- |
236
+ | One wake chain, no forks | atomic Lua claims | queue idempotency keys |
237
+ | Job execution | at-least-once | at-least-once, wider duplicate window |
238
+ | Code-declared jobs | durable in Redis | rebuilt from code after eviction |
239
+ | Runtime `add_job()` | durable, revision-checked | best-effort, lost on eviction |
240
+ | `pause()` | durable, fails closed | best-effort flag plus a queue-borne control message |
241
+
242
+ Under `vercel dev` the cache client falls back to per-process memory, which
243
+ makes the cache backend the zero-infrastructure development mode: the
244
+ queue-serving process drives the schedule, and chain progress travels in the
245
+ messages themselves rather than shared state.
246
+
247
+ ## v1 restrictions
248
+
249
+ - APScheduler 3.x only.
250
+ - Exactly one Redis-backed job store named `default`.
251
+ - The default inline executor only; custom thread/process executors are
252
+ rejected.
253
+ - Jobs declared in code need explicit stable IDs.
254
+ - When the same ID already exists in Redis, declare it with
255
+ `replace_existing=True`. `scheduled_job()` already enables replacement.
256
+ - Runtime mutation APIs require prior activation in that Function instance,
257
+ either automatically on the request or through `scheduler.start()`.
258
+ - Job execution is at-least-once.
259
+
260
+ See [SCHEDULER.md](SCHEDULER.md) for the state machine and failure model. A
261
+ deployable example is in [examples/cleanup](examples/cleanup).