Approval request expiry

ores.inbox.approval_kind carries expires_after_days, and the raise path turns it into the request's expires_at once, at the moment the request is made. A kind that states no days produces a request that never expires, which is the right answer for a kind whose answer is genuinely open-ended. The role request kind states fourteen days.

The policy is therefore data a tenant's deployment can change without a build, and it is stated once for every request of that kind rather than counted again each time one is read.

The decider path is the decide operation: an open request whose expires_at has passed becomes expired instead of being decided, and the decider is told the request expired before they reached it. This path costs nothing and needs no schedule, but it only fires when somebody looks.

The sweep path exists for the queue nobody opens, which is the case a queue rots on. Both paths write the same tail — system.update, and a commentary that says the request closed because nobody answered — so a request's history reads the same however it closed, and a reader cannot tell which path ran. That is deliberate: they are one rule applied twice, not two rules.

ores.scheduler exists to fire actions at stated times, and it already fires system jobs from a row that belongs to no tenant. The sweep is such a row: a job definition carrying action_type = nats_publish and the subject in its payload.

The job publishes the inbox's own expiry operation. It does not run the SQL directly, and that is the load-bearing decision on this page: closing the requests and telling the people who asked are one act, the notice is raised in the service rather than in the store, and an execute_sql job would close requests silently. The job reaches the service for the same reason any other caller does.

A timer inside the service was the first shape this took, and it is the wrong one. Work that lives only inside a steady_timer shares its fate with the lifecycle hook that spawned it, and that hook can silently not fire — see the capture that raised it. A job in the catalogue survives the service restarting, appears in the job list, and can be rescheduled by an operator.

Two things are being decided, and they belong to different people.

That the sweep recurs is the inbox's own behaviour. The inbox owns the requests, so it owns the statement that a request nobody answers must close, and it registers the job itself rather than leaving a row in a populate script that nothing connects back to the component. The job name, the action and the subject are therefore fixed in code and are not configurable.

How often it recurs is the installation's answer, not the inbox's. How often is worth sweeping depends on how many requests a deployment raises and how long its administrators take to answer, and neither the component nor the person writing it can know that. So the schedule is a system setting, carrying a default that suits a small installation. The setting is the same mechanism iam.token.access_lifetime_seconds and system.signup_requires_authorization already use, and the sweep is its first non-variability consumer.

The inbox reads that setting over the wire, through variability.v1.ops.get_setting, and it holds the variability::system_settings:read permission to do it. Reading the table directly would have been shorter and is what this page argues against: a setting is spoken about by name everywhere, the entity read is addressed by an identifier no caller outside variability holds, and a component that reads another's tables has taken a dependency its owner cannot see. The operation answers with the value and its declared type, or says the setting does not exist, so the caller decides what to do about absence rather than discovering it as an empty string.

The split is the point. A component that hardcodes its own schedule is asserting something about somebody else's deployment, and it will be wrong; a component that lets the schedule be set to nothing at all is not offering a sweep. The inbox gets to insist that the work happens and the installation gets to say how often.

Registering at start makes the scheduler a startup dependency, and the failure mode is the one this page exists to prevent: a job that is not there, and nothing saying so. So the service refuses to start when it cannot register the job, and the operator sees why. An installation whose inbox is up but whose requests never expire is worse than one whose inbox is down and says so.

Not every failure is the same, and the two are handled differently. A dependency that is not answering yet — the scheduler has not started, or variability has not — is waited out, because a later attempt can cure it. A setting that is absent, a value that is not a cron expression, or a scheduler that refuses the write are decisions, and repeating them cannot change them, so the service reports the decision at once instead of retrying a mistake twelve times.

The job is recognised by job_name, which is the key the store holds it under, and the registration reuses the identifier of the job already carrying that name. This matters more than it looks: the store keeps one live row per name, so a registration that invented a fresh identifier on every restart would fail against that uniqueness rather than quietly adding a second sweep. A job that already holds the wanted schedule and is active is left alone, so a restart writes no new version of a row nothing changed.

ores_inbox_expire_approval_requests_fn closes every open request whose deadline has passed, and answers one row per request it closed so the caller can tell each person. It is a security-definer function because it reads every tenant, where the rest of the inbox is tenant-scoped by row-level security, and the inbox service is the only role granted execute on it. The read-write role keeps execute too, so the suites can test it.

The notice a decision raises reads "{decider} wrote: {comment}", which for an expiry would name somebody who did nothing. So the expiry has its own notification kind, inbox.approval_expired, whose sentence says the request ran out of time. See Notification requirements.

A request about to run out is read by ores_inbox_remind_expiring_approval_requests_fn, which answers every open request whose expires_at falls between now and now plus the window. The service then warns the holders of the kind's decide permission in the request's own tenant, leaving out the person who asked, because a person never decides their own request.

Warning once is what makes it a warning rather than a nuisance, and the mark is the notice itself: the function leaves out any request a inbox.approval_expiring notification already names. A column on the request was the obvious alternative and was not taken. It would be a second record of the same fact, it would have to be cleared wherever the notice is cleared, and the two could then disagree about whether anybody had been told. Asking the notice costs one not exists and cannot disagree with itself.

The window is the setting inbox.approval_expiry.reminder_window_seconds and the cadence is inbox.approval_expiry.reminder_schedule, so an installation sets both without a build. A window of zero warns nobody, which is what an installation that cannot read the setting gets: a warning nobody receives is better than a service that refuses to start over one.

The reminder does not close anything and the close does not warn. A request answered before its deadline stops matching the warning, and a request the close reaches is no longer open for the warning to find; the two sweeps can run in either order and in any number of repetitions.

A request the sweep already closed is no longer open, so a repeated sweep closes nothing. A sweep that runs while a decider is deciding converges on one answer, because both paths lock the row and both read the same rule. A service that was down for a week sweeps what lapsed in that week on its next run, because the rule is stated over expires_at rather than over an elapsed interval.