Skip to content

Commit 02c9024

Browse files
committed
Merge remote-tracking branch 'origin/main' into share-rename-fix
2 parents cbf996e + 6021ef9 commit 02c9024

3 files changed

Lines changed: 45 additions & 11 deletions

File tree

‎content/(dynamic)/crons.mdx‎

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ A response under 400 is a success and is silent. A response of 400 or worse, or
2323

2424
## Declare it
2525

26-
There is no write API and no dashboard editor. `sf.jsonc` is the only writer, and a publish is the only edit. That is what makes a rollback restore the previous schedules for free.
26+
There is no write API and no dashboard editor. `sf.jsonc` is the only writer, and a publish is the only edit. That is what makes a rollback restore the previous schedules for free, placed against your current allowance.
2727

2828
```jsonc sf.jsonc
2929
{
@@ -43,13 +43,13 @@ Validation is blocking. A bad cron fails the publish rather than shipping a sche
4343

4444
## Schedule syntax
4545

46-
Three grammars. Pick whichever reads best.
46+
Three grammars in two kinds. Named and shorthand schedules are **simple** crons. Five-field crontab schedules are **advanced** crons, and your plan sets how many of each a Space runs.
4747

4848
| Kind | Examples | Notes |
4949
| --- | --- | --- |
50-
| Named | `hourly`, `daily`, `twicedaily`, `weekly` | The provider picks the moment |
51-
| Shorthand | `3h`, `2d`, `1w` | Hours up to 12, days up to 23, weeks up to 6. `N` is at least 1 |
52-
| Crontab | `30 16 * * 1-5`, `*/15 * * * *` | Five fields, down to every minute |
50+
| Named (simple) | `hourly`, `daily`, `twicedaily`, `weekly` | The provider picks the moment |
51+
| Shorthand (simple) | `3h`, `2d`, `1w` | `N` runs per hour, day, or week: `3h` runs three times an hour. Up to 12 an hour, 23 a day, 6 a week |
52+
| Crontab (advanced) | `30 16 * * 1-5`, `*/15 * * * *` | Five numeric fields, down to every minute |
5353

5454
Crontab fields are minute `0-59`, hour `0-23`, day of month `1-31`, month `1-12`, weekday `0-7`. Lists (`1,15`), ranges (`1-5`), `*`, and a `/step` over a span are supported.
5555

@@ -69,7 +69,32 @@ Your schedule string is stored verbatim and never normalized.
6969

7070
Each entry gets a **key** derived by slugging its path. `/api/cron/digest` becomes `api-cron-digest`. Two paths that slug to the same key are rejected at publish.
7171

72-
A Space can declare at most **8** crons.
72+
## Allowance by plan
73+
74+
Each Space runs a set number of simple and advanced crons, by plan:
75+
76+
| Plan | Simple | Advanced | With Boost |
77+
| --- | --- | --- | --- |
78+
| Free | 1 | 0 | No Boost. Upgrade the plan |
79+
| Go | 5 | 0 | 25 simple, 5 advanced |
80+
| Plus | 10 | 5 | 30 simple, 5 advanced |
81+
| Enterprise | 50 | 25 | No Boost |
82+
83+
Boost is a per-Space add-on on Go and Plus. It adds 20 simple crons and raises advanced crons to at least 5, so on Plus it adds simple crons only. Free has no Boost: upgrading the plan is the way to more crons.
84+
85+
Each cron takes a slot of its own kind, in the order you declare them. A later crontab can still take an advanced slot after an earlier simple cron ran out of simple slots:
86+
87+
- A crontab takes an advanced slot while one is left.
88+
- A crontab with no advanced slot left still publishes, with a warning. It runs at its closest simple schedule and counts against the simple allowance. That can run more or less often than the crontab asked, and not at the times it names: `*/5 * * * *` runs `12h` (12 times an hour), and `0 9 * * 1-5` runs `5w` (5 times a week, not necessarily on weekdays at 9:00).
89+
- Crons past the allowance still publish, and the publish carries a warning. Within each kind of slot, the first ones declared run. The rest show as not scheduled, "over this plan's cron limit", on the dashboard's **Crons** page and in `sf crons ls`.
90+
91+
Advanced crons also run at their closest simple schedule for now, until advanced scheduling is enabled for the platform.
92+
93+
A raised limit applies right away. After an upgrade or Boost, crons that were waiting start running without a publish.
94+
95+
A lowered limit applies at your next publish, promote or rollback. Until then, a downgrade or Boost ending changes nothing: crons that are running keep running.
96+
97+
For now, whatever the plan, a Space can declare at most **8** crons, and past that the publish fails validation. Each tier is capped at 8 too, so `allowance` in the API reports the capped numbers (8 simple and 5 advanced on Plus, 8 and 8 on Gold and Enterprise), and Boost adds no crons on a plan already at the cap. The ceiling rises to the plan limits above as the runtime update reaches every box.
7398

7499
## List and trigger
75100

@@ -105,4 +130,13 @@ Only the newest failures are kept, with no history behind them. A real failure a
105130

106131
## API
107132

108-
[`listSpaceCrons`](/api/reference/spaces/listspacecrons) is `GET /v1/spaces/{spaceId}/crons`. It returns the version the schedules came from, which is `null` before the first publish. Each entry carries its key, path, schedule, and recent failures.
133+
[`listSpaceCrons`](/api/reference/spaces/listspacecrons) is `GET /v1/spaces/{spaceId}/crons`. It returns the version the schedules came from, which is `null` before the first publish. Each entry carries its key, path, schedule, and recent failures, plus:
134+
135+
| Field | Meaning |
136+
| --- | --- |
137+
| `scheduled` | Whether the cron runs |
138+
| `tier` | `simple` or `advanced`. `null` when not scheduled |
139+
| `runsAs` | The schedule that actually runs. `null` when not scheduled |
140+
| `reason` | `over_plan_limit` past the allowance, `unsupported_schedule` for a schedule that cannot run. `null` when scheduled |
141+
142+
The response's `allowance` carries the Space's `simple` and `advanced` counts and `upgrade`, the step that unlocks more: `upgrade_plan`, `upgrade_or_boost`, `boost`, or `null` when there is none.

‎content/(reference)/config-file.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ See [Functions](/functions).
202202

203203
| Key | Type | Default | What it does |
204204
| --- | --- | --- | --- |
205-
| `crons` | array, up to 8 entries | none | Scheduled requests |
205+
| `crons` | array, up to 8 entries for now | none | Scheduled requests. Your plan sets how many run, see [Crons](/crons#allowance-by-plan) |
206206
| `crons[].path` | string, up to 512 chars | none | Path to GET. Starts with `/`, no query, no wildcards, no `:placeholders` |
207207
| `crons[].schedule` | string | none | A named schedule, a shorthand, or a five-field crontab |
208208

@@ -236,15 +236,15 @@ See [Redirects, rewrites, and headers](/routing).
236236
| --- | --- |
237237
| File size | 256 KiB |
238238
| `templates` entries | 100 |
239-
| `crons` entries | 8 |
239+
| `crons` entries | 8 for now |
240240
| `crons[].path` | 512 characters |
241241
| `name` | 255 characters |
242242
| `meta.title` | 300 characters |
243243
| `meta.description` | 1000 characters |
244244
| `meta.image`, `meta.favicon` | 2000 characters |
245245
| `superpowers.javascriptTags` entries | 16, each `code` up to 8 KiB |
246246

247-
A plan may lower these caps. None of them can be raised.
247+
A plan may lower these caps. None of them can be raised. The `crons` cap is the same on every plan: your plan sets how many of the declared crons run, see [Crons](/crons#allowance-by-plan).
248248

249249
## The strict v1 shape
250250

‎content/(reference)/limits.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ See [Versions](/versions#how-many-versions-are-kept) for version cleanup.
4141
| Manifest body | 16 MiB | `manifest_body_too_large` |
4242
| `sf.jsonc` file size | 256 KiB | Config validation error |
4343
| Templates in `sf.jsonc` | 100 | `config_templates_over_limit` |
44-
| Cron jobs per space | 8 | Config validation error |
44+
| Cron jobs declared per space | 8 for now, until the runtime update reaches every box. Your plan sets how many run, see [Crons](/crons#allowance-by-plan) | Config validation error |
4545
| Data sources in `sf.jsonc` | 32 | Config validation error |
4646
| Inject snippets | 16, each 8 KiB | Config validation error |
4747
| Redirect rules compiled | 2,100 total, 2,000 static, 100 dynamic | Routing compile error |

0 commit comments

Comments
 (0)