State timeouts and schedules
A state timeout runs one of an actor’s commands when the actor stays in a state too long. A cron schedule runs a command at each due time of a cron expression. Both are declared in the contract and run their command as Akter.System.
Expire a state and run hourly work
- Declare
timeoutsandscheduleson the contract inhold.contract.ts. Each binding names a command that listsAkter.Systemincallersand takesSchema.Void.
hold.contract.ts
import { Cron, Duration, Schema } from "effect"
import { Akter } from "@akterjs/effect/contract"
export const Shopper = Akter.caller("user", Schema.Struct({ id: Akter.PrincipalId }))
export const Held = Schema.TaggedStruct("Held", { checks: Schema.Int })
export const Released = Schema.TaggedStruct("Released", { checks: Schema.Int })
export const Hold = Akter.make("Hold", {
callers: [Shopper, Akter.System],
commands: {
check: Akter.command({
callers: [Akter.System],
errors: [],
from: [Held, Released],
input: Schema.Void,
output: Schema.Void,
to: [Held, Released],
}),
release: Akter.command({
callers: [Akter.System],
errors: [],
from: [Held],
input: Schema.Void,
output: Schema.Void,
to: [Released],
}),
},
initial: { input: Schema.Struct({}), to: Held },
key: Schema.String,
parent: Akter.Root,
queries: {
status: Akter.query({
callers: [Shopper],
errors: [],
input: Schema.Void,
output: Schema.String,
states: [Held, Released],
}),
},
schedules: [Akter.schedule({ command: "check", cron: Cron.parseUnsafe("0 * * * *") })],
states: [Held, Released],
tables: [],
timeouts: [Akter.timeout({ after: Duration.minutes(15), command: "release", state: Held })],
})- Implement the bound commands in
hold.actor.tslike any other command.
hold.actor.ts
import { Effect } from "effect"
import { Held, Hold, Released } from "./hold.contract.ts"
export const HoldLive = Hold.toLayer({
commands: {
check: (hold) => {
const checks = hold.checks + 1
return Effect.succeed({ next: hold._tag === "Held" ? Held.make({ checks }) : Released.make({ checks }) })
},
release: (held) => Effect.succeed({ next: Released.make({ checks: held.checks }) }),
},
initial: () => ({ next: Held.make({ checks: 0 }) }),
queries: {
status: (hold) => Effect.succeed(`${hold._tag} after ${hold.checks} checks`),
},
})- Advance the clock with
story.advanceinhold.story.ts. The timeout fires 15 minutes after the actor entersHeld, and the schedule fires at the start of each hour.
hold.story.ts
import { Effect } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { Story } from "@akterjs/effect/testing"
import { Hold, Shopper } from "./hold.contract.ts"
import { HoldLive } from "./hold.actor.ts"
const as = { caller: Shopper, principal: { id: Akter.PrincipalId.make("ada") } }
const program = Story.run(HoldLive, function* (story) {
yield* story.create(Hold, "cart", { as, input: {} })
const hold = yield* story.actor(Hold, "cart", { as })
yield* story.advance("14 minutes")
console.log(yield* hold.status())
yield* story.advance("1 minute")
console.log(yield* hold.status())
yield* story.advance("1 hour")
console.log(yield* hold.status())
})
Effect.runPromise(program)Text
Held after 0 checks
Released after 0 checks
Released after 1 checksWhy timeouts and schedules live in the contract
A state timeout belongs to a state rather than to a command. Declaring it in the contract lets the host arm and cancel it with the state change, so no handler has to remember to cancel it. A cron schedule has no caller of its own, so it runs as Akter.System. Clients can never send a command that lists only Akter.System.
akter verify reads each timeout as an edge from its state to the to states of its command (verify).
What you can rely on
- State timeouts end with their state. The host arms a state’s timeouts when the actor enters that state. It cancels them in the commit that leaves the state, and re-entering the state starts a new timeout.
- A fired timeout runs once. The in-memory test host runs a timeout’s command one time. A commit, a declared error, a defect, or a refusal all spend the timeout. A failed run rolls back and is not retried. The state gets a new timeout only when the actor leaves it and enters it again.
- Schedules run as the system caller. The host runs each
schedulescommand at every due time of its cron expression, asAkter.System. - Schedules run in UTC. The host reads every cron expression in UTC, whatever the time zone of the machine.
Akter.schedulethrowsInvalidScheduleErrorfor aCronthat carries a time zone. - Schedules fire.
Akter.schedulethrowsInvalidScheduleErrorfor a cron with no future fire time, such as0 0 30 2 *. - Timeouts wait whole milliseconds.
Akter.timeoutthrowsInvalidTimeoutErrorwhenafteris infinite, negative, zero, a fraction of a millisecond, or aboveNumber.MAX_SAFE_INTEGERmilliseconds. - Bound commands. The type checker rejects a timeout or schedule command that does not list
Akter.System, or that takes input. It also rejects a timeout whose command does not list the timeout’s state infrom. - No inline handlers. The
akter/declarative-bindingslint rule rejects a function or a computed name intimeoutsandschedules.