Skip to content

Implement ctx.meta syscalls#95

Open
ianmacartney wants to merge 3 commits intomainfrom
ian/add-syscalls
Open

Implement ctx.meta syscalls#95
ianmacartney wants to merge 3 commits intomainfrom
ian/add-syscalls

Conversation

@ianmacartney
Copy link
Copy Markdown
Member

@ianmacartney ianmacartney commented Apr 10, 2026

Implement getFunctionMetadata syscall and rename transaction metrics APIs

Rename transaction metrics components

  • Rename HeadroomTracker class to TransactionMetricsTracker
  • Rename headroom.ts file to transactionMetrics.ts
  • Update getTransactionHeadroom() method to getTransactionMetrics()
  • Replace 1.0/headroom syscall with 1.0/getTransactionMetrics
  • Update all references from headroom terminology to metrics terminology

Add getFunctionMetadata syscall

  • Implement 1.0/getFunctionMetadata syscall that returns function name and component path
  • Add validation to ensure it can only be called from within a Convex function

Enhance transaction metrics testing

  • Add comprehensive assertions for remaining capacity tracking
  • Add new test case for write operation tracking
  • Verify proper tracking of documents written and bytes written metrics

Summary by CodeRabbit

  • New Features

    • Added 1.0/getFunctionMetrics syscall to retrieve current function metadata including name and component path.
    • Enhanced transaction metrics now provide detailed breakdowns of documents and bytes read/written during transactions.
  • Refactor

    • Updated 1.0/headroom syscall to 1.0/getTransactionMetrics with expanded metric reporting.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Apr 10, 2026

📝 Walkthrough

Walkthrough

The PR renames the headroom tracking system to metrics terminology, replacing HeadroomTracker with TransactionMetricsTracker and getTransactionHeadroom() with getTransactionMetrics(). It updates the corresponding syscall from 1.0/headroom to 1.0/getTransactionMetrics and introduces a new 1.0/getFunctionMetadata syscall. Tests are updated to validate the new metrics syscall structure.

Changes

Cohort / File(s) Summary
Test Updates
convex/bandwidth.test.ts
Updated bandwidth-stats test to use new 1.0/getTransactionMetrics syscall instead of 1.0/headroom, revised assertions to validate metrics fields (documentsRead.used, bytesRead.used, documentsWritten.used, bytesWritten.used), and added document size computations.
Transaction Manager Refactoring
index.ts
Replaced HeadroomTracker with TransactionMetricsTracker throughout; updated getHeadroomTracker() to getMetricsTracker(); swapped 1.0/headroom syscall with 1.0/getTransactionMetrics; added new 1.0/getFunctionMetadata syscall returning function name and component path from execution context.
Metrics Class Renaming
transactionMetrics.ts
Renamed exported class HeadroomTracker to TransactionMetricsTracker and renamed method getTransactionHeadroom() to getTransactionMetrics().

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • convex-test#67: Both PRs modify the transaction bandwidth tracking subsystem, introducing systematic renaming from headroom to metrics terminology and updating the corresponding syscall interface.

Suggested reviewers

  • Nicolapps

Poem

🐰 The headroom tracker hops away,

As metrics take the helm today,

New syscalls bloom, fresh names align,

Transaction secrets now will shine! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'Implement ctx.meta syscalls' is vague and does not clearly convey the main changes, which involve renaming HeadroomTracker to TransactionMetricsTracker and replacing the headroom syscall with getTransactionMetrics and getFunctionMetadata. Consider a more specific title that reflects the primary changes, such as 'Rename headroom to transaction metrics and add getFunctionMetadata syscall' or 'Replace 1.0/headroom with 1.0/getTransactionMetrics and add 1.0/getFunctionMetadata'.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ian/add-syscalls

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Member Author

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

@ianmacartney ianmacartney changed the title implement syscalls Implement ctx.meta syscalls Apr 10, 2026
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Apr 10, 2026

Open in StackBlitz

npm i https://pkg.pr.new/convex-test@95

commit: 5a304c2

@ianmacartney ianmacartney marked this pull request as ready for review April 10, 2026 09:59
Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
convex/bandwidth.test.ts (1)

154-206: Please add coverage for getFunctionMetadata() too.

This file already exercises the syscall surface directly, so it’s a good place to add one happy-path case and one invalid-context case for 1.0/getFunctionMetadata. That would catch context-wiring regressions alongside the new metrics assertions.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@convex/bandwidth.test.ts` around lines 154 - 206, Add two tests invoking the
syscall "1.0/getFunctionMetadata" via (global as any).Convex.asyncSyscall: one
happy-path test inside a valid execution context (use t.query or t.mutation like
the existing tests) that calls asyncSyscall("1.0/getFunctionMetadata",
JSON.stringify({})) and asserts the parsed result contains the expected metadata
fields (e.g., non-empty function name/id/path/runtime) and one invalid-context
test that calls the same syscall outside a valid Convex execution context and
asserts it fails or returns the error shape you expect; reference the existing
test helpers and symbols (convexTest, t.query, t.mutation, getTransactionMetrics
usage, and (global as any).Convex.asyncSyscall) so the tests are added alongside
the current getTransactionMetrics tests.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@index.ts`:
- Around line 1408-1419: getFunctionMetadata currently throws when
executionContextStorage has no store, which occurs for HTTP actions because
fetch() doesn’t install an ExecutionContext before calling httpActionGeneric;
either seed an ExecutionContext for HTTP actions in the fetch() path or narrow
the syscall. Fix by, in the fetch() flow before invoking httpActionGeneric,
create an ExecutionContext (populating udfPath and componentPath from the HTTP
action metadata) and call executionContextStorage.run(storeObj, () =>
httpActionGeneric(...)) so getFunctionMetadata can read ctx; alternatively,
change getFunctionMetadata to detect missing ctx and return a clear value/error
that excludes HTTP actions (adjust the error message and return contract)
instead of assuming executionContextStorage is always present.

---

Nitpick comments:
In `@convex/bandwidth.test.ts`:
- Around line 154-206: Add two tests invoking the syscall
"1.0/getFunctionMetadata" via (global as any).Convex.asyncSyscall: one
happy-path test inside a valid execution context (use t.query or t.mutation like
the existing tests) that calls asyncSyscall("1.0/getFunctionMetadata",
JSON.stringify({})) and asserts the parsed result contains the expected metadata
fields (e.g., non-empty function name/id/path/runtime) and one invalid-context
test that calls the same syscall outside a valid Convex execution context and
asserts it fails or returns the error shape you expect; reference the existing
test helpers and symbols (convexTest, t.query, t.mutation, getTransactionMetrics
usage, and (global as any).Convex.asyncSyscall) so the tests are added alongside
the current getTransactionMetrics tests.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cc997d0d-1518-474a-b76b-59d9430bb43e

📥 Commits

Reviewing files that changed from the base of the PR and between 67cec2d and a88d3ee.

📒 Files selected for processing (3)
  • convex/bandwidth.test.ts
  • index.ts
  • transactionMetrics.ts

Comment on lines +1408 to +1419
case "1.0/getFunctionMetadata": {
const ctx = executionContextStorage.getStore();
if (!ctx) {
throw new Error(
"getFunctionMetadata() can only be called from within a Convex function.",
);
}
return JSON.stringify({
name: ctx.udfPath,
componentPath: ctx.componentPath,
});
}
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

getFunctionMetadata() will reject inside HTTP actions.

Line 1409 assumes every Convex function runs with executionContextStorage, but this file’s fetch() path does not install that context before invoking httpActionGeneric. As written, the new syscall throws from HTTP actions even though they are still Convex functions. Please either seed an ExecutionContext for HTTP actions or narrow the syscall contract/error message to exclude them explicitly.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@index.ts` around lines 1408 - 1419, getFunctionMetadata currently throws when
executionContextStorage has no store, which occurs for HTTP actions because
fetch() doesn’t install an ExecutionContext before calling httpActionGeneric;
either seed an ExecutionContext for HTTP actions in the fetch() path or narrow
the syscall. Fix by, in the fetch() flow before invoking httpActionGeneric,
create an ExecutionContext (populating udfPath and componentPath from the HTTP
action metadata) and call executionContextStorage.run(storeObj, () =>
httpActionGeneric(...)) so getFunctionMetadata can read ctx; alternatively,
change getFunctionMetadata to detect missing ctx and return a clear value/error
that excludes HTTP actions (adjust the error message and return contract)
instead of assuming executionContextStorage is always present.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant