Skip to content

Commit 3f603fa

Browse files
matt-aitkenmatt-aitken
committed
More docs
1 parent 1291996 commit 3f603fa

File tree

6 files changed

+101
-31
lines changed

6 files changed

+101
-31
lines changed

‎docs/mint.json

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -454,7 +454,7 @@
454454
},
455455
{
456456
"group": "Development",
457-
"pages": ["v3/cli-dev", "v3/develop-run-tests"]
457+
"pages": ["v3/cli-dev", "v3/run-tests"]
458458
},
459459
{
460460
"group": "Deployment",
@@ -485,19 +485,16 @@
485485
]
486486
},
487487
"v3/queue-concurrency",
488-
{
489-
"group": "Testing",
490-
"pages": ["v3/run-tests", "v3/automated-tests"]
491-
},
492-
"v3/idempotency",
493488
"v3/versioning",
489+
"v3/machines",
490+
"v3/idempotency",
494491
"v3/reattempting-replaying",
495492
"v3/trigger-filters",
496493
"v3/notifications",
497494
"v3/rollbacks",
498495
"v3/using-apis",
499496
"v3/middleware",
500-
"v3/machines"
497+
"v3/automated-tests"
501498
]
502499
},
503500
{

‎docs/v3/develop-run-tests.mdx

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/v3/machines.mdx

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: "Machines"
3+
description: "Configure the number of vCPUs and GBs of RAM you want the task to use."
4+
---
5+
6+
The `machine` configuration is optional. Using higher spec machines will increase the cost of running the task but can also improve the performance of the task if it is CPU or memory bound.
7+
8+
```ts /trigger/heavy-task.ts
9+
export const heavyTask = task({
10+
id: "heavy-task",
11+
machine: {
12+
cpu: 2,
13+
memory: 4,
14+
},
15+
run: async ({ payload, ctx }) => {
16+
//...
17+
},
18+
});
19+
```

‎docs/v3/middleware.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Middleware"
3+
description: "This function is called before the `run` function, it allows you to wrap the run function with custom code."
4+
---
5+
6+
<Snippet file="incomplete-docs.mdx" />

‎docs/v3/versioning.mdx

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: "Versioning"
3+
description: "We use atomic versioning to ensure that started tasks are not affected by changes to the task code."
4+
---
5+
6+
A version is a bundle of tasks at a certain point in time.
7+
8+
## Version identifiers
9+
10+
Version identifiers look like this:
11+
12+
- `20240313.1` - March 13th, 2024, version 1
13+
- `20240313.2` - March 13th, 2024, version 2
14+
- `20240314.1` - March 14th, 2024, version 1
15+
16+
You can see there are two parts to the version identifier:
17+
18+
- The date (in reverse format)
19+
- The version number
20+
21+
Versions numbers are incremented each time a new version is created for that date and environment. So it's possible to have `20240313.1` in both the `dev` and `prod` environments.
22+
23+
## Version locking
24+
25+
When a task run starts it is locked to the latest version of the code (for that environment). Once locked it won't change versions, even if you deploy new versions. This is to ensure that a task run is not affected by changes to the code.
26+
27+
### Child tasks and version locking
28+
29+
Trigger and wait functions version lock child task runs to the parent task run version. This ensures the results from child runs match what the parent task is expecting. If you don't wait then version locking doesn't apply.
30+
31+
| Trigger function | Parent task version | Child task version | isLocked |
32+
| ----------------------- | ------------------- | ------------------ | -------- |
33+
| `trigger()` | `20240313.2` | Latest | No |
34+
| `batchTrigger()` | `20240313.2` | Latest | No |
35+
| `triggerAndWait()` | `20240313.2` | `20240313.2` | Yes |
36+
| `batchTriggerAndWait()` | `20240313.2` | `20240313.2` | Yes |
37+
38+
## Local development
39+
40+
When running the local server (using `npx trigger.dev dev`), every relevant code change automatically creates a new version of all tasks.
41+
42+
So a task run will continue running on the version it was locked to. We do this by spawning a new process for each task run. This ensures that the task run is not affected by changes to the code.
43+
44+
## Deployment
45+
46+
Every deployment creates a new version of all tasks for that environment.
47+
48+
## Retries and reattempts
49+
50+
When a task has an uncaught error it will [retry](/v3/errors-retrying), assuming you have not set `maxAttempts` to 0. Retries are locked to the original version of the run.
51+
52+
If all the attempts have failed you can start a [reattempt](/v3/reattempting-replaying). This will be version locked to the original version of the run.
53+
54+
## Replays
55+
56+
A "replay" is a new run of a task that uses the same inputs but will use the latest version of the code. This is useful when you fix a bug and want to re-run a task with the same inputs. See [replays](/v3/reattempting-replaying) for more information.

‎docs/v3/writing-tasks-introduction.mdx

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,19 @@ Before digging deeper into the details of writing tasks, you should read the [fu
88

99
## Writing tasks
1010

11-
| Topic | Description |
12-
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
13-
| [Logging](/v3/logging) | View and send logs and traces from your tasks. |
14-
| [Errors](/v3/errors) | Handle errors in your tasks. |
15-
| [Retrying](/v3/retrying) | Configure retrying of entire tasks and individual blocks of code. |
16-
| [Wait](/v3/wait) | Wait for periods of time or for external events to occur before continuing. |
17-
| [Queues](/v3/queues) | Set task concurrency at the task level as well as per-tenant. |
18-
| [Testing](/v3/testing) | Test your tasks with payloads from the dashboard or write automated tests in code. |
19-
| [Idempotency](/v3/idempotency) | Protect against mutations happening twice. |
20-
| [Versioning](/v3/versioning) | How versioning works. |
21-
| [Replaying](/v3/replaying) | Replay tasks with the same payload as before. |
22-
| [Notifications](/v3/notifications) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. |
23-
| [Environment Variables](/v3/environment-variables) | How to set and use Environment variables. |
24-
| [Machines](/v3/machines) | Configure the CPU and RAM of the machine your task runs on |
25-
| [Rollbacks](/v3/rollbacks) | Rollback code inside a task when errors happen to provide transactional guarantees. |
26-
| [Using APIs](/v3/using-apis) | How to use APIs from within your tasks. |
27-
| [Trigger filters](/v3/trigger-filters) | Prevent unwanted filters where the payload doesn't match your filter. |
28-
| [Middleware](/v3/middleware) | Middleware can wrap the task run function. |
11+
| Topic | Description |
12+
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
13+
| [Logging](/v3/logging) | View and send logs and traces from your tasks. |
14+
| [Errors & retrying](/v3/errors-retrying) | How to deal with errors and write reliable tasks. |
15+
| [Wait](/v3/wait) | Wait for periods of time or for external events to occur before continuing. |
16+
| [Concurrency & Queues](/v3/queue-concurrency) | Configure what you want to happen when there is more than one run at a time. |
17+
| [Versioning](/v3/versioning) | How versioning works. |
18+
| [Machines](/v3/machines) | Configure the CPU and RAM of the machine your task runs on |
19+
| [Idempotency](/v3/idempotency) | Protect against mutations happening twice. |
20+
| [Reattempting & Replaying](/v3/reattempting-replaying) | You can reattempt a task that has failed all of its attempts. You can also replay a task with a new version of your code. |
21+
| [Notifications](/v3/notifications) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. |
22+
| [Rollbacks](/v3/rollbacks) | Rollback code inside a task when errors happen to provide transactional guarantees. |
23+
| [Using APIs](/v3/using-apis) | How to use APIs from within your tasks. |
24+
| [Trigger filters](/v3/trigger-filters) | Prevent unwanted filters where the payload doesn't match your filter. |
25+
| [Middleware](/v3/middleware) | Middleware can wrap the task run function. |
26+
| [Automated tests](/v3/automated-tests) | Write automated tests in code. |

0 commit comments

Comments
 (0)