apairon
491f495c66
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
188 lines
4.9 KiB
Markdown
188 lines
4.9 KiB
Markdown
---
|
|
name: scheduled-jobs-and-automation
|
|
description: Build scheduled background workflows with tibi-server jobs. Covers cron design, job context, safe automation patterns, reporting/cleanup/sync use cases, and how jobs interact with hooks, audit, and realtime.
|
|
---
|
|
|
|
# scheduled-jobs-and-automation
|
|
|
|
## When to use this skill
|
|
|
|
Use this skill when:
|
|
|
|
- A project needs scheduled cleanup, reporting, imports, syncs, reminders, or maintenance tasks
|
|
- You want automation without an incoming HTTP request
|
|
- Jobs should update data, send mail, call APIs, or emit realtime events
|
|
- You need to decide whether logic belongs in a hook, an action, or a job
|
|
|
|
## Goal
|
|
|
|
The goal is to design jobs as reliable background workflows, not as miscellaneous scripts.
|
|
|
|
Jobs on this stack are:
|
|
|
|
- cron-triggered
|
|
- goja-based JavaScript programs
|
|
- independent of HTTP requests
|
|
- able to use many of the same server-side packages as hooks
|
|
|
|
## Source of truth
|
|
|
|
Use these sources when implementing or reviewing jobs:
|
|
|
|
- `tibi-server/docs/11-jobs.md`
|
|
- `tibi-server/docs/10-audit.md`
|
|
- `tibi-server/docs/07-realtime.md`
|
|
- `api/config.yml`
|
|
|
|
## Hook vs. action vs. job
|
|
|
|
Choose the right execution surface.
|
|
|
|
- **Hook**: request-coupled logic around CRUD or actions
|
|
- **Action**: endpoint-style business workflow triggered by an explicit call
|
|
- **Job**: scheduled background automation without an incoming request
|
|
|
|
Do not place scheduled logic into hooks just because the code already exists there.
|
|
|
|
## Good use cases
|
|
|
|
Strong job use cases:
|
|
|
|
- cleanup of old documents or temp data
|
|
- periodic report generation
|
|
- scheduled API synchronization
|
|
- cache warming or maintenance tasks
|
|
- reminder and digest emails
|
|
- scheduled realtime announcements
|
|
|
|
Weak use cases:
|
|
|
|
- workflows that must run immediately on user action
|
|
- logic that depends on live request/response objects
|
|
- features that need interactive user feedback during execution
|
|
|
|
## Job configuration
|
|
|
|
Every job should define:
|
|
|
|
- cron schedule
|
|
- file path
|
|
- timeout when appropriate
|
|
- optional metadata via `meta`
|
|
|
|
Treat cron frequency as a product and operations decision. Do not set aggressive schedules without a real need.
|
|
|
|
## Job context limits
|
|
|
|
Jobs have broad server-side access, but they are not request-driven.
|
|
|
|
Important consequences:
|
|
|
|
- no `request`
|
|
- no `response`
|
|
- no `user.*`
|
|
- no `cookie.*`
|
|
- no `channel.subscribe`
|
|
- `channel.send` is available
|
|
|
|
If the logic depends on request context, it does not belong in a job.
|
|
|
|
## Safe automation patterns
|
|
|
|
Jobs should be:
|
|
|
|
- idempotent where possible
|
|
- bounded in runtime
|
|
- explicit in filters and update scope
|
|
- observable through logs or downstream effects
|
|
|
|
Avoid “run and mutate everything” jobs without clear selection criteria.
|
|
|
|
## Interaction with audit and realtime
|
|
|
|
Jobs are not isolated from other system behavior.
|
|
|
|
- DB operations from jobs appear in audit with `source.type: "job"`
|
|
- jobs can emit realtime events through `channel.send`
|
|
|
|
This makes jobs useful for background workflows that should still be visible operationally.
|
|
|
|
## Recommended job patterns
|
|
|
|
### Cleanup job
|
|
|
|
Recommended shape:
|
|
|
|
- explicit age threshold
|
|
- narrow filter
|
|
- bounded timeout
|
|
- optional reporting of removed count
|
|
|
|
### Scheduled reporting
|
|
|
|
Recommended shape:
|
|
|
|
- aggregate counts or summaries
|
|
- render a report template if needed
|
|
- send mail or store result
|
|
|
|
### External sync
|
|
|
|
Recommended shape:
|
|
|
|
- pull from external API
|
|
- normalize data
|
|
- update local records idempotently
|
|
- log enough context for troubleshooting
|
|
|
|
### Scheduled notifications
|
|
|
|
Recommended shape:
|
|
|
|
- compute upcoming or due events
|
|
- send mail, action-like side effect, or realtime signal
|
|
- avoid duplicate sends through clear state checks
|
|
|
|
## Operational concerns
|
|
|
|
When adding a job, decide:
|
|
|
|
- how often it runs
|
|
- what timeout it needs
|
|
- whether reruns are safe
|
|
- how failure is detected
|
|
- whether a manual rerun path exists
|
|
|
|
Jobs should not become invisible critical infrastructure.
|
|
|
|
## Anti-patterns
|
|
|
|
- Using jobs for logic that belongs in request-time hooks or actions
|
|
- Overly frequent cron schedules for expensive tasks
|
|
- No timeout on potentially slow network-heavy jobs
|
|
- Broad destructive updates without precise filters
|
|
- Silent failures with no observable output or effect
|
|
|
|
## Verification checklist
|
|
|
|
After adding a job, verify all of these:
|
|
|
|
1. The cron schedule matches the real business need.
|
|
2. The job logic does not rely on request-only APIs.
|
|
3. Timeout and runtime expectations are reasonable.
|
|
4. Repeated execution does not corrupt data.
|
|
5. Any audit/realtime side effects are intentional.
|
|
6. `yarn validate` stays clean.
|
|
|
|
## What an LLM should inspect first
|
|
|
|
When asked to automate something on this starter, inspect in this order:
|
|
|
|
1. `tibi-server/docs/11-jobs.md`
|
|
2. whether the trigger is scheduled, request-driven, or manual
|
|
3. whether the logic needs audit visibility or realtime side effects
|
|
4. the project config area where the job will be declared
|
|
5. the exact data mutation scope
|
|
|
|
This prevents turning cron tasks into unbounded background risk.
|