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 6, 2026 2:34am
rivetkit-serverless	Error		Jan 6, 2026 2:34am

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
rivet-cloud	Ignored		Jan 6, 2026 2:34am
rivet-inspector	Ignored	Preview	Jan 6, 2026 2:34am

[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(engine): return error for pending actors #3730 : 2 dependent PRs (#3675 , #3740 )
• 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

Summary

This PR adds documentation for the abort signal feature in Rivet Actors, covering both automatic shutdown cancellation and manual cancellation patterns. The additions are well-structured and provide clear examples for both use cases.

✅ Strengths

Clear Documentation Structure

• The documentation is logically organized with cross-references between related sections
• Examples progress from simple (automatic cancellation) to complex (manual cancellation with chaining)
• Good use of bidirectional links between actions.mdx and lifecycle.mdx

Practical Examples

• The c.abortSignal example in lifecycle.mdx (lines 627-638) is concise and shows the simplest use case
• The manual cancellation example in actions.mdx (lines 255-277) demonstrates the more advanced pattern with proper cleanup

Consistent with Project Style

• Examples follow TypeScript conventions used throughout the documentation
• The code style matches existing examples (using actor from rivetkit, proper typing, etc.)
• Proper capitalization of "Rivet Actor" as a proper noun per CLAUDE.md guidelines

🔍 Issues & Suggestions

1. Potential Race Condition in Manual Cancellation Example

Location: website/src/content/docs/actors/actions.mdx:260-262

const controller = new AbortController();
c.vars.controller = controller;
c.abortSignal.addEventListener("abort", () => controller.abort());

Issue: There's a subtle race condition here. If the actor is already shutting down when this action starts, c.abortSignal might already be aborted. The event listener would be added but never fire because the abort event has already occurred.

Recommendation: Check if the signal is already aborted:

const controller = new AbortController();
c.vars.controller = controller;

// Handle both cases: already aborted or will abort
if (c.abortSignal.aborted) {
  controller.abort();
} else {
  c.abortSignal.addEventListener("abort", () => controller.abort());
}

2. Missing Error Handling in Examples

Locations:

• actions.mdx:264-268
• lifecycle.mdx:629-635

Issue: The fetch examples don't handle abort errors. When an abort signal fires, fetch throws an AbortError which should typically be handled separately from other errors.

Recommendation: Add error handling to show best practices:

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

  return await response.json();
} catch (error) {
  if (error.name === 'AbortError') {
    // Operation was cancelled, this is expected
    return null; // or throw a UserError if appropriate
  }
  throw error; // Re-throw other errors
}

3. Vars Type Definition Could Be More Explicit

Location: actions.mdx:256

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

Minor Issue: While this works, it's slightly redundant. Consider simplifying to:

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

This is more explicit about the return type and follows the pattern used elsewhere in lifecycle.mdx (e.g., line 104).

4. Missing Context About When Abort Signal Fires

Location: lifecycle.mdx:621

Issue: The section says "when the actor is stopping" but doesn't clarify what events trigger this:

• Sleep due to inactivity?
• Explicit destroy call?
• Server shutdown?
• All of the above?

Recommendation: Add a brief clarification:

The `c.abortSignal` provides an `AbortSignal` that fires when the actor is stopping (during sleep, destroy, or server shutdown). Use this to cancel ongoing operations gracefully.

📊 Test Coverage

Status: N/A (Documentation only)

No tests needed for documentation changes, but consider:

• Testing the example code snippets to ensure they compile and work as expected
• Adding a note in the examples about expected behavior when operations are cancelled

🔒 Security Considerations

Status: ✅ Good

• The abort signal pattern is a security-positive feature as it helps prevent resource leaks
• No security concerns with the documentation itself

⚡ Performance Considerations

Status: ✅ Good

• Using abort signals is a performance best practice for cancellable operations
• The manual cancellation pattern prevents unnecessary work when actors shut down

📝 Minor Suggestions

1. Consistency in example naming: The lifecycle example uses chatActor while the actions example also uses chatActor. Consider using different names to make it clear these are separate examples (e.g., llmActor vs chatActor).

2. Consider adding a note about cleanup: In the manual cancellation example (actions.mdx), you might want to mention that when the cancel action is called, the ongoing fetch will be aborted, which means the generate action will throw an error that should be handled.

✅ Overall Assessment

This is a solid documentation addition that fills an important gap. The examples are clear and the cross-references make it easy for users to find the right pattern for their use case. With the minor improvements suggested above (particularly the race condition fix and error handling), this will be excellent documentation.

Recommendation: Approve with suggested improvements for error handling and race condition handling.

---

Generated by Claude Code - Code review based on Rivet project standards and best practices

[graphite-app]

Merge activity

• Jan 6, 2:19 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:20 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:20 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:21 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:22 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:22 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:31 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:31 AM UTC: CI is running for this pull request on a draft pull request (#3754) due to your merge queue CI optimization settings.
• Jan 6, 2:32 AM UTC: Merged by the Graphite merge queue via draft PR: #3754.