refactor(rivetkit): make traces server only lib by jog1t · Pull Request #4051 · rivet-dev/rivet

jog1t · 2026-01-27T20:10:39Z

No description provided.

jog1t · 2026-01-27T20:11:08Z

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(dashboard): workflows ui #4081
feat(dashboard): traces timeline ui #4056
refactor(rivetkit): make traces server only lib #4051 👈 (View in Graphite)
feat(frontend): traces ui #4038 : 1 other dependent PR (#4032 )
feat(rivetkit): traces #4037
feat(rivetkit): integrate workflows in to actors #4006
feat(rivetkit): workflows #3734
feat(rivetkit): add actor run handler #4005 : 1 other dependent PR (#4008 )
feat: actor messages & queues #3989 : 2 other dependent PRs (#4002 , #4088 )
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 · 2026-01-27T20:12:40Z

PR Review: refactor(rivetkit): make traces server only lib

Summary

This PR refactors the @rivetkit/traces package to be server-only by adding a browser stub that throws helpful errors when used in browser environments. It also replaces the fdb-tuple dependency with a forked version @rivetkit/fdb-tuple and includes formatting/linting improvements.

✅ Code Quality & Best Practices

Strong Points:

Clear browser compatibility strategy: The new browser.ts stub provides clear, helpful error messages when users try to use server-only functionality in the browser
Type-only exports for browsers: Correctly exports types from the browser entry point, allowing type checking without bundling Node.js code
Package.json exports configuration: Proper use of conditional exports with the browser field taking precedence over default imports
Dependency migration: Clean migration from fdb-tuple to @rivetkit/fdb-tuple across both traces and workflow-engine packages

Code Style Issues:
The PR includes extensive formatting changes (reformatting function parameters, line breaks, etc.) that make the diff harder to review. According to CLAUDE.md:

Do not run ./scripts/cargo/fix.sh. Do not format the code yourself.

While this is a TypeScript PR (not Rust), the same principle applies - formatting changes should ideally be separated or avoided unless necessary.

🐛 Potential Issues

1. Dependency Management Concern ⚠️

The PR uses a pkg.pr.new URL for the dependency:

"@rivetkit/fdb-tuple": "https://pkg.pr.new/rivet-dev/fdb-tuple/@rivetkit/fdb-tuple@32f95e2"

Issues:

This appears to be a preview/temporary deployment URL for testing PRs
The hash 32f95e2 references a specific commit, which is fragile for production
If this is meant to be permanent, it should use a proper npm registry version or Git URL

Recommendation:

If the fork is ready for use, publish it to npm with proper versioning
If this is temporary, add a TODO comment and issue reference
Consider using a Git URL format: "@rivetkit/fdb-tuple": "git+https://github.com/rivet-dev/fdb-tuple.git#commit-or-tag"

2. Removed Code Without Context

In workflow-engine/src/keys.ts, the PR removes helper functions:

-function bufferToUint8Array(buf: Buffer): Uint8Array {
-  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-}
-
-function uint8ArrayToBuffer(arr: Uint8Array): Buffer {
-  return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);
-}

These were removed because the new @rivetkit/fdb-tuple likely returns Uint8Array directly instead of Buffer. This is good, but:

Ensure the forked library truly returns Uint8Array consistently
Verify no other code depends on Buffer-specific behavior

3. Build Configuration

The package.json build script now includes:

tsup src/index.ts src/reader.ts src/browser.ts

But tsup.config.ts doesn't specify any special handling for the browser entry. Verify that:

tsup correctly generates separate bundles for each entry point
The browser bundle doesn't include Node.js APIs (crypto, async_hooks, etc.)
Consider adding platform: 'browser' to tsup config for the browser entry

🔒 Security Concerns

No significant security issues, but:

The use of a preview deployment URL (pkg.pr.new) in production dependencies is concerning from a supply chain security perspective
The URL is mutable (could point to different code if the preview is regenerated)

⚡ Performance Considerations

Positive:

Removed unnecessary Buffer conversions in workflow-engine/src/keys.ts, directly using Uint8Array
Browser bundles won't include unused Node.js polyfills

Neutral:

Formatting changes don't impact runtime performance

🧪 Test Coverage

Good:

Tests were updated to use @rivetkit/fdb-tuple instead of fdb-tuple
Test logic remains unchanged, indicating the API is compatible
Import order was corrected (Node.js imports before external packages)

Could Be Better:

No tests verify the browser stub behavior
Consider adding a test that imports from the browser entry point and expects errors

📝 Documentation & Comments

Issue:
According to CLAUDE.md:

Write comments as normal, complete sentences. Avoid fragmented structures with parentheticals and dashes

The comment in browser.ts:2 is fine, but could be more complete:

// Browser stub for @rivetkit/traces
// This file is used as the browser entry point to prevent Node.js-specific code from being bundled

Better:

// Browser stub for @rivetkit/traces.
// This file serves as the browser entry point to prevent Node.js-specific code 
// from being bundled in client applications. All functions throw helpful errors.

🎯 Recommendations

High Priority:
- Replace the pkg.pr.new URL with a stable dependency source (published npm package or Git URL)
- Verify the forked @rivetkit/fdb-tuple returns Uint8Array consistently
Medium Priority:
- Add browser stub tests to verify error messages
- Consider splitting formatting changes into a separate commit
- Add platform-specific tsup config for browser builds
Low Priority:
- Improve comment formatting per CLAUDE.md guidelines
- Document why the fork of fdb-tuple was necessary (in a comment or PR description)

✨ Overall Assessment

Verdict: Approved with Minor Concerns ⚠️

The refactoring is well-executed and the browser stub pattern is a clean solution. The main concern is the temporary dependency URL which should be addressed before merging to production. The code changes are sound, tests pass, and the architectural decision makes sense.

Key Blocker:

Resolve the pkg.pr.new dependency URL before merging

Nice to Have:

Browser stub tests
Cleaner git history (separate formatting commits)

pkg-pr-new · 2026-01-27T20:13:36Z

More templates

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4051

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@4051

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4051

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4051

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4051

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4051

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4051

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4051

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4051

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4051

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4051

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4051

commit: 471f2e8

graphite-app · 2026-01-27T20:15:14Z

Graphite Automations

"Test" took an action on this PR • (01/27/26)

1 assignee was added to this PR based on Kacper Wojciechowski's automation.

graphite-app · 2026-01-27T20:18:09Z

rivetkit-typescript/packages/traces/tests/traces.test.ts

+	async list(
+		prefix: Uint8Array,
+	): Promise<Array<{ key: Uint8Array; value: Uint8Array }>> {


The function parameter formatting should be consistent with the project's style guide. Run Biome linter with --apply to automatically format this function declaration.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-01-27T20:23:46Z

rivetkit-typescript/packages/traces/package.json

 		"@rivetkit/bare-ts": "^0.6.2",
 		"cbor-x": "^1.6.0",
-		"fdb-tuple": "^1.0.0",
+		"@rivetkit/fdb-tuple": "https://pkg.pr.new/rivet-dev/fdb-tuple/@rivetkit/fdb-tuple@32f95e2",


The custom URL dependency '@rivetkit/fdb-tuple': 'https://pkg.pr.new/rivet-dev/fdb-tuple/@rivetkit/fdb-tuple@32f95e2' is causing TypeScript compilation errors during CI. Consider using a standard npm package, a GitHub URL (github:rivet-dev/fdb-tuple#commit-hash), or adding a resolution in the root package.json to help resolve this URL correctly.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-01-27T20:23:48Z

rivetkit-typescript/packages/workflow-engine/package.json

 		"@rivetkit/bare-ts": "^0.6.2",
 		"cbor-x": "^1.6.0",
-		"fdb-tuple": "^1.0.0",
+		"@rivetkit/fdb-tuple": "https://pkg.pr.new/rivet-dev/fdb-tuple/@rivetkit/fdb-tuple@32f95e2",


The custom URL dependency '@rivetkit/fdb-tuple': 'https://pkg.pr.new/rivet-dev/fdb-tuple/@rivetkit/fdb-tuple@32f95e2' is causing TypeScript compilation errors during CI. Consider using a standard npm package, a GitHub URL (github:rivet-dev/fdb-tuple#commit-hash), or adding a resolution in the root package.json to help resolve this URL correctly.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-04T20:40:00Z

rivetkit-typescript/packages/traces/src/traces.ts

@@ -26,6 +25,7 @@ import {
 	type SpanUpdate,
 	type StringId,
 	type TraceId,
+	type Record as TraceRecord,


The imports from schemas/versioned.js are not properly grouped and ordered. Constants like CHUNK_VERSIONED and CURRENT_VERSION should be grouped together, not interspersed with type imports. This violates Biome's import organization rules.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-04T20:40:02Z

rivetkit-typescript/packages/traces/src/browser.ts

+// Browser stub for @rivetkit/traces
+// This file is used as the browser entry point to prevent Node.js-specific code from being bundled
+
+import type {
+	OtlpAnyValue,
+	OtlpExportTraceServiceRequestJson,
+	OtlpInstrumentationScope,
+	OtlpKeyValue,
+	OtlpResource,
+	OtlpResourceSpans,
+	OtlpScopeSpans,
+	OtlpSpan,
+	OtlpSpanEvent,
+	OtlpSpanLink,
+	OtlpSpanStatus,
+} from "./otlp.js";
+import type {
+	EndSpanOptions,
+	EventOptions,
+	ReadRangeOptions,
+	ReadRangeResult,
+	ReadRangeWire,
+	SpanHandle,
+	SpanStatusInput,
+	StartSpanOptions,
+	Traces,
+	TracesDriver,
+	TracesOptions,
+	UpdateSpanOptions,
+} from "./types.js";
+
+function notSupported(name: string): never {
+	throw new Error(
+		`@rivetkit/traces: ${name} is not supported in the browser. Traces are only available on the server.`,
+	);
+}
+
+export function createTraces(
+	_options: TracesOptions<OtlpResource>,
+): Traces<OtlpExportTraceServiceRequestJson> {
+	notSupported("createTraces");
+}
+
+export function encodeReadRangeWire(_wire: ReadRangeWire): Uint8Array {
+	notSupported("encodeReadRangeWire");
+}
+
+export function decodeReadRangeWire(_bytes: Uint8Array): ReadRangeWire {
+	notSupported("decodeReadRangeWire");
+}
+
+export function readRangeWireToOtlp(
+	_wire: ReadRangeWire,
+	_resource?: OtlpResource,
+): { otlp: OtlpExportTraceServiceRequestJson; clamped: boolean } {
+	notSupported("readRangeWireToOtlp");
+}
+
+// Re-export types (these are safe for browsers)
+export type {
+	EndSpanOptions,
+	EventOptions,
+	ReadRangeOptions,
+	ReadRangeResult,
+	ReadRangeWire,
+	SpanHandle,
+	SpanStatusInput,
+	StartSpanOptions,
+	Traces,
+	TracesDriver,
+	TracesOptions,
+	UpdateSpanOptions,
+	OtlpAnyValue,
+	OtlpExportTraceServiceRequestJson,
+	OtlpInstrumentationScope,
+	OtlpKeyValue,
+	OtlpResource,
+	OtlpResourceSpans,
+	OtlpScopeSpans,
+	OtlpSpan,
+	OtlpSpanEvent,
+	OtlpSpanLink,
+	OtlpSpanStatus,
+};


This new file likely has formatting issues throughout. Since it's a completely new file, it should be formatted according to Biome's rules. Run 'biome format --write' on this file to ensure proper formatting.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

jog1t marked this pull request as ready for review January 27, 2026 20:10

graphite-app bot assigned jog1t Jan 27, 2026

jog1t mentioned this pull request Jan 27, 2026

feat(rivetkit): traces #4037

Closed

jog1t mentioned this pull request Jan 27, 2026

feat(frontend): traces ui #4038

Closed

graphite-app bot reviewed Jan 27, 2026

View reviewed changes

NathanFlurry changed the base branch from 01-24-feat_frontend_traces_ui to graphite-base/4051 January 28, 2026 01:11

This was referenced Jan 28, 2026

feat(rivetkit): workflows #3734

Closed

feat(rivetkit): integrate workflows in to actors #4006

Closed

workflow example #4032

Closed

feat(rivetkit): add icon & name customization #4033

Closed

jog1t force-pushed the graphite-base/4051 branch from 4189086 to 3c7fabc Compare January 28, 2026 19:55

jog1t force-pushed the 01-27-refactor_rivetkit_make_traces_server_only_lib branch from 471f2e8 to 63d40ba Compare January 28, 2026 19:55

jog1t changed the base branch from graphite-base/4051 to 01-24-feat_frontend_traces_ui January 28, 2026 19:56

jog1t mentioned this pull request Jan 28, 2026

feat(dashboard): traces timeline ui #4056

Draft

NathanFlurry changed the base branch from 01-24-feat_frontend_traces_ui to graphite-base/4051 January 30, 2026 08:19

refactor(rivetkit): make traces server only lib

d77a4fc

jog1t force-pushed the 01-27-refactor_rivetkit_make_traces_server_only_lib branch from 63d40ba to d77a4fc Compare January 30, 2026 21:29

jog1t force-pushed the graphite-base/4051 branch from 3c7fabc to 0232d12 Compare January 30, 2026 21:29

jog1t changed the base branch from graphite-base/4051 to 01-24-feat_frontend_traces_ui January 30, 2026 21:29

jog1t mentioned this pull request Jan 30, 2026

feat(dashboard): workflows ui #4081

Draft

NathanFlurry changed the base branch from 01-24-feat_frontend_traces_ui to graphite-base/4051 February 3, 2026 20:02

This was referenced Feb 4, 2026

feat(workflow): add workflow history inspector integration #4111

Closed

feat: use cases #4100

Draft

feat: sqlite #3666

Draft

graphite-app bot reviewed Feb 4, 2026

View reviewed changes

jog1t closed this Feb 4, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(rivetkit): make traces server only lib#4051

refactor(rivetkit): make traces server only lib#4051
jog1t wants to merge 1 commit intographite-base/4051from
01-27-refactor_rivetkit_make_traces_server_only_lib

jog1t commented Jan 27, 2026

Uh oh!

jog1t commented Jan 27, 2026 •

edited by NathanFlurry

Loading

Uh oh!

claude bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 27, 2026

Uh oh!

graphite-app bot commented Jan 27, 2026

Uh oh!

graphite-app bot Jan 27, 2026

Uh oh!

graphite-app bot Jan 27, 2026

Uh oh!

graphite-app bot Jan 27, 2026

Uh oh!

graphite-app bot Feb 4, 2026

Uh oh!

graphite-app bot Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jog1t commented Jan 27, 2026

Uh oh!

jog1t commented Jan 27, 2026 • edited by NathanFlurry Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

claude bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: refactor(rivetkit): make traces server only lib

Summary

✅ Code Quality & Best Practices

🐛 Potential Issues

1. Dependency Management Concern ⚠️

2. Removed Code Without Context

3. Build Configuration

🔒 Security Concerns

⚡ Performance Considerations

🧪 Test Coverage

📝 Documentation & Comments

🎯 Recommendations

✨ Overall Assessment

Uh oh!

pkg-pr-new bot commented Jan 27, 2026

Uh oh!

graphite-app bot commented Jan 27, 2026

Graphite Automations

Uh oh!

graphite-app bot Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jog1t commented Jan 27, 2026 •

edited by NathanFlurry

Loading

claude bot commented Jan 27, 2026 •

edited

Loading