Call back a delayed send and restore a trashed entry

Merged
JE
2d ago
+2802-43

HEY's Undo Send and its restore-from-Trash for a single entry were the two routes a caller needed to take back a send or a deleted draft, and both sat in spec/excluded-routes.json. This models them, so the hosted HEY MCP server can offer "undo that send" and "bring that draft back" without driving the paths by hand.

What it adds

  • UndoTopicSend: POST /topics/{topicId}/undo_send.json. Calls back the last message the caller sent on a topic while Undo Send still holds it. The message is a draft again, unsent.
  • RestoreEntry: PUT /entries/{entryId}/status/active.json. Takes one entry out of the Trash. Idempotent: an entry that isn't in the Trash is left as it is.

Both leave excluded-routes.json for route-coverage.json, and every generated client gains the two operations.

HEY answers both with a 303 and no body, and for the undo that redirect's Location is the only place HEY names the entry it called back (/messages/{id}/edit for a message on its own thread, /topics/{topicId}?expanded_draft={id} for a reply). HEY picks the entry, the caller's last delayed one on the topic, so it need not be the one the caller meant. The hand-written layer therefore takes the redirect as the answer rather than follow it:

Undo, answering the entryReading an entry out of a Location
GoTopics().UndoSend(ctx, topicID) (entryID int64, err error)UndoneEntryID(location) (int64, bool)
RustTopics::undo_topic_send(topic_id) -> Result<Option<i64>, Error>services::undone_entry_id(&str) -> Option<i64>
KotlinTopicsService.undoTopicSend(topicId): Long?undoneEntryId(String): Long?
SwiftTopicsService.undoTopicSend(topicId:) -> Int?undoneEntryId(_:) -> Int?

Go also gains Entries().Restore(ctx, entryID) error, which takes its redirect the same way, so a failed read of the thread can't report a restore that went through as one that didn't, and Client.PutForm, which completes the form family beside PostForm and DeleteForm.

Too late is told from undone. With nothing left to call back (the delay ran out and the message went, or none was held) HEY answers 400 and changes nothing. Every SDK surfaces that as an API error whose HTTP status is 400. A success is a nil error and, from the conveniences, the entry.

The undo is never resent. A second undo would call back the next delayed entry on the thread, so UndoTopicSend is one attempt, whatever the client's retry settings. RestoreEntry is idempotent and retries a 429 or 503 once.

SentMessage.undo_action's comment said HEY offers a scoped token no Undo Send. It does now, to a token holding write approved since HEY widened that scope, and the comment says so.

How it was checked against HEY

Read from haystack's master, and exercised there with controller tests against a local build (not against production):

  • Topics::UndoSendsController#create undoes topic.last_delayed_entry_for(user:) and redirects to the draft, or answers 400 when there is none. Entry::Delayable holds a send for 15 seconds and offers the undo for 12.
  • Entries::StatusController#active restores the entry alone. A draft that was its topic's only entry took the topic to the Trash with it, and restoring just the entry leaves a draft on a trashed topic. RestoreTopic is the call for that one, and the operation's comment says which to use when.
  • Scopes: both take write (approved since the widening). Restoring a draft that is scheduled to send needs send as well, since a draft keeps its schedule in the Trash.

Nothing in haystack changes for this, and no existing caller of either route sees a difference.

TypeScript

The TypeScript client follows no redirect and reports any non-2xx as an error, so there a successful undoTopicSend or restoreEntry throws a HeyError whose httpStatus is 303, with no Location. That is documented on the two methods and in typescript/README.md, and held by typescript/tests/client.test.ts, rather than changed here: making a redirect an answer in TypeScript is a transport change that deserves its own PR (a model-level "the redirect is the answer" trait would also let the other generated clients stop following). Four conformance cases that need a followed or captured redirect are marked not applicable for TypeScript for the same reason.

Tests

  • Go, Rust, Kotlin and Swift unit tests: both Location shapes, a bare /topics/{id} not read as an undo, non-positive ids refused, the 400, one request after a 503.
  • Go: only a 302 or a 303 is the answer to an undo or a restore. A 301, 307 or 308 is not followed and is an error with its status, as in the other SDKs' redirect capture.
  • Conformance: two path cases, and six behaviour cases in conformance/tests/undo-restore.json (the entry out of each Location shape, the 400, no resend of an undo after a 503 from either layer, one resend of a restore). Go, Rust, Kotlin and Swift run 237 of 237; TypeScript runs 228 with 9 not applicable.
  • make check passes on the head.
  • Mutation check on the conveniences: 24 of 24 caught (eight in each of Rust, Kotlin and Swift: redirect followed, either Location shape unread, non-positive ids accepted, a bare topic read as an undo, the 400 swallowed or unworded, a resend after 503).

Additive. No release, tag or version bump here.