Internal operations
Run follow-up work as the same caller, call an outside service from an action, start outside work from the browser, and run jobs from a cron.
An operation often starts more work: it schedules an action that calls an
outside service, and that action reads and writes again. Build those
functions with internalQuery, internalMutation and internalAction from
convex/functions.ts. The caller travels with every call, and each internal
operation checks it again.
import { fail } from '@lupinum/better-convex-functions'
import { v } from 'convex/values'
import { internal } from './_generated/api'
import { mutation } from './functions'
/** A person asks for a summary. The slow part runs later, as the same person. */
export const request = mutation({
action: 'projects.summarize',
args: { projectId: v.id('projects') },
returns: v.null(),
handler: async (ctx, { projectId }) => {
const project = await ctx.db.get(projectId)
if (project?.status !== 'active') fail('NOT_FOUND', 'This project is not active.')
await ctx.scheduler.runAfter(0, internal.summaryWork.build, { projectId })
return null
},
})import { fail, oneLine } from '@lupinum/better-convex-functions'
import { v } from 'convex/values'
import { internal } from './_generated/api'
import { internalAction, internalMutation, internalQuery } from './functions'
/** Work outside the database. Reads and writes go through internal operations. */
export const build = internalAction({
args: { projectId: v.id('projects') },
handler: async (ctx, { projectId }) => {
const { name } = await ctx.runQuery(internal.summaryWork.load, { projectId })
const response = await fetch('https://summaries.example.com/v1/summarize', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ text: name }),
})
if (!response.ok) throw new Error(`The summary service answered ${response.status}.`)
const { summary } = (await response.json()) as { summary: string }
await ctx.runMutation(internal.summaryWork.save, { projectId, summary })
return null
},
})
export const load = internalQuery({
action: 'projects.summarize',
args: { projectId: v.id('projects') },
returns: v.object({ name: v.string() }),
handler: async (ctx, { projectId }) => {
const project = await ctx.db.get(projectId)
if (!project) fail('NOT_FOUND', 'No project with this ID.')
return { name: project.name }
},
})
export const save = internalMutation({
action: 'projects.summarize',
args: { projectId: v.id('projects'), summary: v.string() },
returns: v.null(),
handler: async (ctx, { projectId, summary }) => {
// Text from an outside service: one line, no control characters, at most 500 characters.
await ctx.db.patch(projectId, { summary: oneLine(summary, 500) })
return null
},
})Keep internal operations in a module of their own, as convex/summaryWork.ts
here. Then each module of public operations has a
leak test with one
entry per export, and the internal operations need none: only your own code
calls them.
What travels with a call
ctx.runQuery, ctx.runMutation, ctx.runAction and ctx.scheduler work as
in Convex. You pass the arguments; the library adds who acts. The internal
operation then:
- checks the caller again: the grant of an agent, and whether the user may
still act (your
userfunction); - checks its own action against the policy, with the caller's role in the tenant its arguments name;
- runs its handler with the row rules applied.
So a scheduled follow-up stops when the person loses access between the two calls. This includes cleanup that the follow-up does as that person: see Keep short-lived statuses correct.
Work that a call schedules is part of that call:
- It takes no second rate-limit token from a bucket that the call already took one from.
- For an agent, it checks again who acts: the grant, the person and their role. It does not check the timing again: the agent's turn, whether the run still runs, and the age of the MCP access token. So the follow-up of an allowed tool finishes after the agent took its next turn, after the run ended, and after the access token expired. Turning the agent off or disconnecting the host stops it.
An agent's follow-up keeps the agent's scopes and agent rules. An internal
operation whose action needs approval runs only under an approval of that
agent's request. An internal mutation without an agent rule needs approval
too, so give an internal write that an allowed tool runs its own 'allow'.
It runs under an approval:
- while
approveruns the request, and - for one hour after the person approved it, for the work the request
scheduled. An approved request that starts a paid check, calls out from an
internalActionand records the result works this way.
A pending, declined, failed or older approval grants nothing. A revoked connection stops its follow-ups, because each call checks the grant again. Like the request itself, they change only the rows of the approved plan and rows that work created.
ctx.scheduler.cancel cancels only the jobs that the same person or agent
scheduled. The ID of another job fails with NOT_FOUND, the same answer as
for a job that does not exist. An action has no database to look the job up,
so it cancels only the jobs it scheduled in the same call. A job that runs as
the system may cancel any job.
internalAction
An internal action has no action name and no database. It reads and writes
only through ctx.runQuery and ctx.runMutation of internal operations.
ctx.actor is who it acts for, as the caller passed it. It is checked in each
of those calls, not when the action starts.
Public actions
Some work starts in the browser and runs outside the database: render a PDF,
read a file that a person uploaded, import a CSV file, or call a service while
the person waits. Build it with action. Before the handler runs, the call
checks the caller, the policy and the tenant that the arguments name, as a
public mutation does. It also takes the action's
limit token.
A Convex action has no database, so the check runs in an internal mutation of
its own: authorizeAction. Export it from convex/functions.ts, and give its
reference to fns.action once, as the convex/functions.ts file in
Row rules does:
export const { authorizeAction } = fns
export const action = fns.action(internal.functions.authorizeAction)Then build each public action with action. This one makes the summary from
the first example while the person waits, and reuses its internal operations:
import { v } from 'convex/values'
import { internal } from './_generated/api'
import { action } from './functions'
/** The summary of a project, made now. The summary service runs outside the database. */
export const summarize = action({
action: 'projects.summarize',
args: { projectId: v.id('projects') },
returns: v.string(),
handler: async (ctx, { projectId }) => {
const { name } = await ctx.runQuery(internal.summaryWork.load, { projectId })
const response = await fetch('https://summaries.example.com/v1/summarize', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ text: name }),
})
if (!response.ok) throw new Error(`The summary service answered ${response.status}.`)
const { summary } = (await response.json()) as { summary: string }
await ctx.runMutation(internal.summaryWork.save, { projectId, summary })
return summary
},
})What the check does, and what it does not do:
- A person whose role does not allow the action gets
FORBIDDEN. A signed-out visitor getsNOT_SIGNED_IN, unless the action is inpublic. The handler does not run. - The role comes from the tenant that an ID in the arguments names. A call
that names no tenant needs the role outside any tenant
(
roleOf(ctx, user, null)), unless its action is public. - The arguments name IDs from one place, as in a mutation without
crossTenant. An action has nocrossTenant. ctx.actoris the caller that the check found. The handler has noctx.db:ctx.runQuery,ctx.runMutation,ctx.runActionandctx.schedulerreach internal operations as that caller, and each one checks it again.- The check takes the action's token. A mutation that the handler runs with
ctx.runMutationtakes no second token from the same bucket. A mutation with another bucket (another action, or another tenant) takes its own token. The token stays spent when the handler fails later: an action has no transaction. - The check writes no audit row. Each audited internal mutation that the handler runs writes its own row.
- A file ID (
v.id('_storage')) names no tenant, andctx.storagereads any file. Never read a file by an ID from the arguments. Take the ID from a row that an internal query of the action may read, so the row rules decide:const { fileId } = await ctx.runQuery(internal.imports.upload, { uploadId }). - An action is not a tool. Agents reach your application through tools only.
If an agent needs the same work, write a mutation with a
toolfield that schedules an internal action. The internal action runs as the agent, also after the agent's turn or run ended.
Raw functions cannot be reached
An operation cannot call a function built with Convex's own builders. The call fails, and nothing that the call did is kept, even when the handler catches the error.
An internal or public action has no transaction. When it reaches a raw function, the raw function's writes are already committed; the action fails loudly. The no-bypass test is what prevents this: it fails while a raw internal function exists.
Component functions, such as a rate limiter or a workpool, are not your functions. They get their arguments unchanged.
Jobs
A job is internal code that the system runs: a cron, or cleanup that the
cron schedules. Its actor is { kind: 'system', job }. It gets the database
without row rules, and every run adds one row to the activity feed with the
job's result. Return a Convex value; a result larger than 64 KiB is kept as
{ truncated: true, bytes }.
A cron starts a job, not an internal operation: an internal operation needs to
know who acts. The job's ctx.runQuery, ctx.runMutation, ctx.runAction
and ctx.scheduler reach internal operations and internal actions as the
system, as in an operation. So a cron that must call an outside service
starts a job, and the job schedules the internal action.
Only a cron or another job may start a job. In an operation, an internal
operation or an internal action, passing a job to ctx.runMutation or
ctx.scheduler is a type error that says so. (Without types, the call fails
with Job <name> runs from a cron or another job, not from an operation.) To
start system work from an operation, write a row that the job reads at its
next run, as a queue.
import { v } from 'convex/values'
import { internal } from './_generated/api'
import { internalAction, job } from './functions'
const year = 365 * 24 * 60 * 60 * 1000
/** Deletes projects that were archived more than a year ago. */
export const removeOldProjects = job({
name: 'removeOldProjects',
args: {},
handler: async (ctx) => {
const old = await ctx.db
.query('projects')
.withIndex('by_status_archived', (q) =>
q
.eq('status', 'archived')
.gt('archivedAt', 0)
.lt('archivedAt', Date.now() - year),
)
.take(500)
for (const project of old) await ctx.db.delete(project._id)
await ctx.scheduler.runAfter(0, internal.cleanup.report, { removed: old.length })
return { removed: old.length }
},
})
/** Tells the team chat how many projects the cleanup removed. */
export const report = internalAction({
args: { removed: v.number() },
handler: async (_ctx, { removed }) => {
const response = await fetch('https://chat.example.com/hooks/cleanup', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ text: `Removed ${removed} archived projects.` }),
})
if (!response.ok) throw new Error(`The chat answered ${response.status}.`)
return null
},
})import { cronJobs } from 'convex/server'
import { internal } from './_generated/api'
const crons = cronJobs()
crons.daily(
'remove old projects',
{ hourUTC: 3, minuteUTC: 0 },
internal.cleanup.removeOldProjects,
{},
)
export default cronsA job sees every tenant. Keep jobs small, and never start one from input that a person or an agent controls.
Keep short-lived statuses correct
Scheduled work runs as the person or agent whose call scheduled it. When they
lose access (they leave the tenant, their account is disabled, or the agent is
turned off), each ctx.runQuery and ctx.runMutation that acts for them is
refused. Revoking access does not stop an outside effect, such as an email or a
payment, that an internalAction makes before such a call. Cleanup stops too. A handler that sets a row from
processing to failed, or removes a half-done upload, is refused, and the
row stays processing.
Give each status that must change soon a path that does not depend on the person or agent:
- A cron job that sweeps old rows. For example, a row that is
processingfor more than 10 minutes becomesfailed. - A status that you derive from time when you read it. Store when the work
started, and show a row that is
processingfor more than 10 minutes as failed.
Do not run a failure handler as the actor whose call just failed. When the call failed because the actor lost access, the failure handler fails for the same reason. Let the sweep set the final status.
Build the sweep like removeOldProjects in Jobs: store when the work
started, give the table an index on the status and that time, take a batch of
rows that are processing and older than 10 minutes, and set each to failed.
Run it from a cron every few minutes.