Guides
Reservations for async work
Reserve before expensive work starts, then commit or release when the work finishes.
Use reservations when work can start, fail, or be cancelled after Valqio allows it.
Good fits:
- video rendering
- long report export
- AI generation jobs
- paid marketplace API calls
- background jobs with worker retries
Flow
- Begin the generated action before queuing work.
- Store the action transaction ID with your job record.
- Let one worker claim the transaction.
- Commit after successful work.
- Release after failure or cancellation.
export async function enqueueVideo(requestId: string) {
const customer = videoApp.customer(
{ id: 'workspace_acme' },
{ requestId },
)
const transaction = await customer.actions.videos.render.begin({
quantity: 1,
idempotencyKey: `render-video:${requestId}`,
expiresIn: 'PT15M',
})
await jobs.enqueue({
requestId,
actionTransactionId: transaction.transactionId,
})
}
export async function runVideoJob(job: VideoJob) {
const customer = videoApp.customer(
{ id: 'workspace_acme' },
{ requestId: job.requestId },
)
const claimed = await customer.actions.videos.render.claim({
transactionId: job.actionTransactionId,
})
let video
try {
video = await renderVideo()
} catch (error) {
await customer.actions.videos.render.release({
transactionId: claimed.transactionId,
failure: {
code: error instanceof Error ? error.name : 'WORK_FAILED',
message: error instanceof Error ? error.message : String(error),
},
})
throw error
}
await customer.actions.videos.render.commit({
transactionId: claimed.transactionId,
})
return video
}Rules
- Commit only after the product work succeeds.
- Release if work fails before completion.
- Use one caller-owned idempotency key when the action begins.
- Persist the action transaction ID with the job before it can be delivered.
- Treat
action_work_pendingas another worker owning the product work. - Keep commit outside the product-work
catch. - If commit remains uncertain, reconcile the transaction. Do not release completed work.
- If release remains uncertain, reconcile the same transaction before retrying product work.
- Log request ID, action key, and transaction ID for support.
After the job settles, inspect Runtime Activity and Decisions → History in Console.