api: require Response wrapper on custom methods and return DrainWorkerResponse from DrainWorker #2411

Out of all 10 custom (non-CRUD) RPCs in pkg/proto/ateapipb/ateapi.proto, 9 return a <Method>Response wrapper message (SuspendActorResponse, PauseActorResponse, ResumeActorResponse, RevertActorResponse, MintActorJWTResponse, MintActorCertificateResponse,
RegisterWorkerResponse, MintAteomActorCertificateResponse, RequestActorSuspendResponse).

Control.DrainWorker is the sole outlier returning a resource directly:

rpc DrainWorker(DrainWorkerRequest) returns (Worker) {}

Meanwhile, docs/api-style-guide.md §4 ("Custom Methods") still shows an outdated rpc SuspendActor(SuspendActorRequest) returns (Actor) {} snippet and states:

Custom methods should return a response message matching the RPC name, with a Response suffix. When operating on a specific resource, a custom method may return the resource itself.

Returning a dedicated <Method>Response wrapper on all custom methods keeps the API uniform and allows adding method-specific output fields later (like ResumeActorResponse.resumed) without breaking wire compatibility.

Proposal

1. Update docs/api-style-guide.md §4 ("Custom Methods"):
   • Require custom methods to return a response message named {MethodName}Response (removing the allowance to return the resource directly). Sounds safer.
   • Update the SuspendActor example snippet to return SuspendActorResponse.
2. In pkg/proto/ateapipb/ateapi.proto, change Control.DrainWorker to return DrainWorkerResponse:

   rpc DrainWorker(DrainWorkerRequest) returns (DrainWorkerResponse) {}
   
   // DrainWorkerResponse holds the drained Worker.
   message DrainWorkerResponse {
     // worker as it stands after the drain, in WORKER_STATE_TERMINATING.
     Worker worker = 1;
   }

3. Regenerate protobufs (hack/update/codegen.sh) and update DrainWorker handlers and callers (cmd/ateapi, cmd/atecontroller, cmd/benchmarking/isolate/fake-workersync).
4. Add a lint rule in tools/apitool enforcing that custom (non-CRUD) methods return {MethodName}Response.

Tim Hockin (@thockin)