Skip to content

ateapi: accept optional preconditions on custom methods - #4046

Open
haiyanmeng wants to merge 1 commit into
agent-substrate:mainfrom
haiyanmeng:custom-method-preconditions
Open

haiyanmeng wants to merge 1 commit into
agent-substrate:mainfrom
haiyanmeng:custom-method-preconditions

Conversation

@haiyanmeng

@haiyanmeng haiyanmeng commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

SuspendActor, ResumeActor, RevertActor, DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable act on whichever resource holds the name when the call arrives. A client that read the resource earlier can act on a different one if the name was deleted and recreated in between.

Each of these requests now accepts an optional Preconditions message, with the same uid and version guards as DeleteOptions. A guard that does not match returns ABORTED. An unset guard is not checked, so existing clients see no change.

  • Suspend, Resume and Revert check the guards on the actor they read under the actor lease. Resume also checks before taking the lease, and never retries a worker assignment against an actor recreated after a failed bind. Under a version guard, Resume aborts if the actor changes during worker assignment or node detach, instead of retrying on the newer version.
  • Suspend checks before returning an already suspended actor, so a stale call cannot report success for a different actor.
  • RequestActorSuspend now sends the uid and version of the actor it checked. The workflow refuses the actor if it was resumed onto another worker, or deleted and recreated, before the workflow took the lease. On that ABORTED, the worker gets NotFound if it no longer hosts the actor, and retries otherwise.
  • A uid conflict in a Suspend, Resume or Revert write now returns ABORTED instead of INTERNAL.

Version skew: preconditions is a new optional field. An older ate-api-server rejects a request that sets it with INVALID_ARGUMENT, so clients must not set it until every replica runs this version. Requests that leave it unset work on both versions.

MintActorJwt is the only other custom method on Control. It doesn't change the actor, so it takes no guards.

Addresses #1773

AI use: I used Claude Code to review the diff, rebase onto main, and draft the commit message and this description. I reviewed all of it.

  • Tests pass
  • Docs updated

@haiyanmeng haiyanmeng added kind/feature An enhancement / feature request or implementation area/api-machinery labels Nov 20, 2026
@haiyanmeng haiyanmeng added this to the v1.1 milestone Nov 20, 2026
@haiyanmeng
haiyanmeng force-pushed the custom-method-preconditions branch 2 times, most recently from bf23cc8 to ea25959 Compare November 20, 2026 23:00
SuspendActor, ResumeActor, RevertActor, DrainWorker, MarkWorkerAvailable
and MarkWorkerUnavailable act on whichever resource holds the name when
the call arrives. A client that read the resource earlier can act on a
different one if the name was deleted and recreated in between.

Add a Preconditions message with the same optional uid and version
guards as DeleteOptions, and accept it on each of these requests. The
server checks it against the resource it loads and returns ABORTED on a
mismatch. Suspend checks before returning an already suspended actor,
so a stale call cannot report success for a different actor.

RequestActorSuspend sends the uid and version of the actor it checked
as preconditions. The workflow then refuses an actor that was recreated,
or resumed onto another worker, after the check. The worker still gets
NotFound for an actor it no longer hosts.

ResumeActor no longer retries a worker assignment against an actor
recreated after the failed bind. Its template and guards were checked
against the old one. Under a version guard, it also aborts when the
actor changes during worker assignment or node detach, instead of
retrying on the newer version.

actorWriteError now reports a uid conflict apart from a version
conflict. Suspend, Resume and Revert and their workflow steps use it,
so a uid conflict returns ABORTED instead of INTERNAL, in both the RPC
status and the lifecycle metric.

Signed-off-by: Haiyan Meng <haiyanmeng@google.com>
@haiyanmeng
haiyanmeng force-pushed the custom-method-preconditions branch from ea25959 to cc0fe5b Compare November 20, 2026 23:03
@juli4n

Copy link
Copy Markdown
Collaborator

Can we scope this PR down to actor lifecycle methods?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/api-machinery kind/feature An enhancement / feature request or implementation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants