chore(docs): document abort signal

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
rivet-site	Ready	Preview, Comment	Jan 2, 2026 11:37pm
rivetkit-serverless	Error		Jan 2, 2026 11:37pm

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
rivet-cloud	Ignored		Jan 2, 2026 11:37pm
rivet-inspector	Ignored	Preview	Jan 2, 2026 11:37pm

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(dash): surface actor errors in ui #3743
• fix(dash): use ineligible icon for runners #3742
• feat(dash): show runner pool errors #3741
• chore: update engine-full sdk #3740
• feat(engine): return error for pending actors #3730
• chore(gas): add support for find_workflows #3739
• chore(docs): document abort signal #3673 👈 (View in Graphite)
• chore(rivetkit): clean up logging configuration #3672
• chore(rivetkit): RIVET_EXPOSE_ERRORS #3671
• chore(rivetkit): specialize context types for better compiler errors #3669
• fix(rivetkit): fix c.client not respecting correct origin #3668
• fix(rivetkit): allow providing no args to createRivetKit #3667
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Document Abort Signal

Overview

This PR adds documentation for the abort signal feature in Rivet Actors, covering both automatic cleanup on actor shutdown and manual cancellation of long-running operations.

---

Code Quality & Documentation ✅

Strengths:

• Clear, practical examples that demonstrate real-world use cases
• Good cross-referencing between the two new sections (actions.mdx ↔ lifecycle.mdx)
• Consistent with existing documentation style and patterns
• Examples follow TypeScript best practices

---

Suggestions for Improvement

1. Expand the Manual Cancellation Example (actions.mdx:248-280)

The current example shows chaining c.abortSignal with a custom AbortController, but it has a subtle issue:

Issue: The custom controller stored in c.vars.controller could be overwritten if multiple generate actions run concurrently, making cancel potentially abort the wrong operation.

Suggestion: Consider adding a note about this limitation or showing a more robust pattern for handling multiple concurrent operations, or add a comment explaining the single-operation assumption.

---

2. Add Error Handling Guidance (actions.mdx:248-280)

When an AbortSignal fires, fetch throws an AbortError. Consider showing how to handle this gracefully in the documentation.

---

3. Clarify Timing of c.abortSignal (lifecycle.mdx:619-641)

The documentation states the signal fires "when the actor is stopping" but doesnt clarify the exact timing:

• Does it fire before onSleep?
• Does it fire before onDestroy?
• What happens if an action is still running?

Consider adding a brief note about the lifecycle order.

---

4. Consider Adding a Warning

Since onSleep might not always fire (as noted in lifecycle.mdx:196), consider adding a note that c.abortSignal is more reliable for cleanup in crash scenarios.

---

Security Considerations ✅

No security concerns. The examples demonstrate proper signal handling without introducing vulnerabilities.

---

Performance Considerations ✅

The examples are efficient:

• Properly chains abort signals without creating unnecessary listeners
• Cleans up resources appropriately
• No performance anti-patterns

---

Test Coverage

Question: Are there existing tests for c.abortSignal behavior? Consider adding tests that verify:

• Signal fires during actor sleep
• Signal fires during actor destroy
• In-flight operations are properly cancelled
• Multiple operations handle abortion correctly

---

Minor Suggestions

1. Consistency: In actions.mdx:262, consider using c.abortSignal.addEventListener("abort", ...) on a separate line for readability (matching the style in lifecycle.mdx:632)

2. Link verification: Ensure the cross-reference links work correctly:

   • /docs/actors/lifecycle#actor-shutdown-abort-signal
   • /docs/actors/actions#canceling-long-running-actions

---

Summary

This is a solid documentation addition that fills an important gap. The examples are practical and well-written. The suggestions above would make the documentation even more robust by addressing edge cases and providing clearer guidance on error handling and concurrent operations.

Recommendation: ✅ Approve with minor suggestions

The PR is good to merge as-is, but consider the suggestions above for a future iteration to make the documentation more comprehensive.

[claude]

PR Review: Document Abort Signal

This PR adds documentation for the c.abortSignal feature in RivetKit actors. Overall, the documentation is clear and well-structured. Here's my detailed feedback:

---

✅ Strengths

1. Good Cross-Referencing: The PR properly cross-references between the two new sections ("Canceling Long-Running Actions" and "Actor Shutdown Abort Signal"), making it easy for users to navigate between related concepts.

2. Clear Examples: Both code examples are practical and demonstrate real-world use cases (fetch cancellation and manual cancellation).

3. Appropriate Placement: The sections are well-placed within their respective documents (actions.mdx and lifecycle.mdx).

4. Consistent with Existing Patterns: The documentation style matches the existing documentation format and tone.

---

🔍 Suggestions & Improvements

1. Type Safety in Examples (Minor)

In actions.mdx lines 256-262, the createVars example uses a nullable type pattern:

createVars: () => ({ controller: null as AbortController | null }),

Suggestion: Consider using AbortController | undefined instead of null for consistency with TypeScript best practices, or explain why null is preferred here.

2. Error Handling (Moderate)

Both examples show fetch operations but don't demonstrate error handling for abort scenarios:

const response = await fetch("https://api.example.com/generate", {
  method: "POST",
  body: JSON.stringify({ prompt }),
  signal: controller.signal
});

Suggestion: Add a note or example showing how to handle AbortError:

try {
  const response = await fetch("https://api.example.com/generate", {
    method: "POST",
    body: JSON.stringify({ prompt }),
    signal: c.abortSignal
  });
  return await response.json();
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Request was cancelled');
    return null; // or throw a UserError
  }
  throw err;
}

This would help users understand the full lifecycle of abort operations.

3. Chaining Pattern Explanation (Minor)

In actions.mdx line 262, the chaining pattern is used but could be better explained:

c.abortSignal.addEventListener("abort", () => controller.abort());

Suggestion: Add a brief comment explaining why this chaining is necessary (to ensure the custom controller aborts when the actor shuts down, in addition to manual cancellation).

4. Memory Leak Concern (Minor)

The example stores the AbortController in c.vars.controller and overwrites it on each generate call. If a second generate call happens before the first completes, the first controller reference is lost.

Suggestion: Either:

• Add a note that this is simplified for demonstration
• Show a more robust pattern with cleanup:

  generate: async (c, prompt: string) => {
    // Clean up previous controller if exists
    c.vars.controller?.abort();
    
    const controller = new AbortController();
    c.vars.controller = controller;
    c.abortSignal.addEventListener("abort", () => controller.abort());
    // ...
  }

5. Response Handling (Minor)

Both examples use:

return await response.json();

Suggestion: Add error handling for invalid JSON or non-200 responses to make the examples more production-ready, or add a note that error handling is omitted for brevity.

---

🔒 Security Considerations

No security concerns identified. The examples use fetch with external APIs, which is appropriate for documentation purposes.

---

🧪 Test Coverage

This is documentation-only, so no test coverage required. However, consider:

• Verifying that the code examples actually compile and run correctly
• Ensuring the cross-reference links work properly when deployed

---

📊 Performance Considerations

No performance concerns. The abort signal pattern is appropriate for canceling long-running operations.

---

📝 Minor Fixes

1. Consistency in method names: The example uses c.vars.controller?.abort() in the cancel action. Consider adding a note about when this might return early (if controller is null/undefined).

---

✨ Overall Assessment

This is a solid documentation addition that fills an important gap. The abort signal feature is crucial for building robust actors, and this documentation makes it accessible.

Recommendation: ✅ Approve with minor suggestions

The suggestions above are mostly enhancements that would make the documentation even more helpful, but the PR is ready to merge as-is if you prefer to iterate on these improvements later.

---

Review generated by Claude Code