Skip to content

Describe River's non-Go clients without referring to River Go - #1506

Draft
bgentry wants to merge 1 commit into
masterfrom
bg/describe-clients-without-go
Draft

bgentry wants to merge 1 commit into
masterfrom
bg/describe-clients-without-go

Conversation

@bgentry

@bgentry bgentry commented Oct 14, 2026

Copy link
Copy Markdown
Contributor

River's Rust, JavaScript, Ruby, and Java clients document much of their behavior by comparison with River Go: "like River for Go's Config.FetchCooldown", "a Go duration such as 1h", "aligned like Go River's by-period uniqueness". All of River's clients keep the same features and design, but each is its own piece of software, and someone using only the Rust client shouldn't need to know anything about the Go one to understand it. This rewrites those references so each client is documented on its own terms.

The change covers what users of a client actually see: public API doc comments (rustdoc, TSDoc on exported APIs, Ruby docs on public methods, Javadoc), READMEs and docs pages, CLI help, the gem and Maven package descriptions, user-facing error messages, and the regenerated JavaScript API reports. Each reference now states the behavior directly. For example, the duration grammar @every accepts and the epoch that by-period uniqueness windows align to are spelled out, and the zero time is given as 0001-01-01T00:00:00Z. Where the point is interop through a shared database, schema, or wire format, the text refers to "other River clients sharing the database" instead of naming Go.

Some references are kept on purpose. Changelogs, including released entries, can still mention alignment with Go, and so can internal implementation comments and docs on private items, which explain why something works the way it does. Tests and conformance code compare implementations by design. Guides about running a client alongside Go services (Rust's mixed deployment guide and mixed_go_rust example, JavaScript's "Running alongside Go and Rust" doc and mixed-language example) keep Go where it's the subject. Java's API comparison, differences, and validation documents exist to compare with Go and are left as is. Contributor docs still describe the Go tooling development needs, such as generating fixtures and syncing migrations. Code identifiers like go_time aren't renamed.

A few user-visible messages change wording. Accepted input formats don't change.

Where Before After
Rust JobArgs derive, invalid duration expected a Go duration such as "1h" expected a duration such as "1h"
Rust unique args, empty path segment … is empty, which River Go cannot hash … is empty and can't be part of a unique key
JavaScript unique path segment that reads as an array index … which River Go treats as an array index … can't match Go's … which other River clients treat as an array index … the unique key wouldn't match theirs
JavaScript cron schedule crossing a skipped day … River Go never returns from this schedule … so no later occurrence can be computed
Ruby @every duration out of range @every duration exceeds Go's duration range @every duration must fit in signed 64-bit nanoseconds
Rust and JavaScript bench help "a Go-style duration", "matches River's Go and Rust benchmarks" "a duration such as 30s, 5m, or 1h30m", "matches the benchmarks of River's other implementations"

River's Rust, JavaScript, Ruby, and Java clients document much of their
behavior by comparison with River Go: "like River for Go's
`Config.FetchCooldown`", "a Go duration such as `1h`", "aligned like Go
River's by-period uniqueness". Each port is its own piece of software,
and a user of one shouldn't need to know River Go to understand it.

Rewrite those references in user-facing text to describe the behavior
directly: public API doc comments, READMEs and docs pages, CLI help, a
gem and Maven package description, and error messages. Where the point
is interop through a shared database, schema, or wire format, the text
now refers to other River clients. For example, the duration grammar
`@every` accepts and the epoch by-period windows align to are spelled
out, and a list cursor's format is described as shared by every River
client.

Error messages that compared with Go now describe the problem instead:
the derive macro's invalid duration, an empty unique-args path segment
in Rust, a JavaScript unique path segment other clients read as an array
index, a cron schedule that can't pass a skipped day, and an
out-of-range Ruby `@every` duration. Accepted input formats don't
change.

Documents about running alongside Go keep their Go references, as do
contributor docs for tooling that needs Go, the Java documents that
compare its API with Go's, internal comments, tests, conformance code,
and changelogs. The JavaScript API reports are regenerated.

@brandur brandur left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Yeah good call!

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.

2 participants