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
- Reserve before work starts.
- Store the reservation ID with your job record.
- Commit after successful work.
- Release after failure or cancellation.
The recordPendingValqio* and markValqio*Applied calls below represent app-owned durable storage. A reconciliation worker should retry any pending operation with the same idempotency key.
export async function runReservedVideo(requestId: string) {
const subject = { type: 'customer' as const, key: 'workspace_acme' }
const keys = runtime.lifecycle.createIdempotencyKeys(`render-video:${requestId}`)
const reserved = await runtime.lifecycle.reserve({
requestId,
meterKey: 'video-renders',
quantity: 1,
subject,
idempotencyKey: keys.reserve,
expiresIn: 'PT15M',
})
if (!reserved.allowed || !reserved.reservation?.reservationId) {
return {
status: 402,
body: {
reasonCode: reserved.reasonCode,
requestId,
},
}
}
const reservationId = reserved.reservation.reservationId
let video
try {
video = await renderVideo()
} catch (error) {
await recordPendingValqioRelease({
reservationId,
requestId,
idempotencyKey: keys.release,
})
await runtime.lifecycle.releaseWithRetry({
reservationId,
requestId,
idempotencyKey: keys.release,
metadata: { reason: 'work_failed' },
})
await markValqioReleaseApplied(reservationId)
throw error
}
await recordPendingValqioCommit({ reservationId, requestId, idempotencyKey: keys.commit })
await runtime.lifecycle.commitWithRetry({
reservationId,
requestId,
idempotencyKey: keys.commit,
})
await markValqioCommitApplied(reservationId)
return video
}Rules
- Commit only after the product work succeeds.
- Release if work fails before completion.
- Reuse the same commit key when commit is retried.
- Reuse the same release key when release is retried.
- Persist commit intent after work succeeds and before attempting commit.
- Persist release intent before releasing failed or cancelled work.
- If commit remains uncertain after retries, reconcile the pending commit with the same key. Do not release completed work.
- If release remains uncertain after retries, reconcile the pending release with the same release key.
- Log request ID, idempotency keys, and reservation ID for support.
After the job settles, inspect Runtime Activity and Decisions → History in Console.