Give the Rust crate examples that compile, a README walkthrough at Go depth, and a formatting pin

Merged
JE
2mo ago
+631-21

Docs, examples and the local-equals-CI devex for the Rust crate (card: hey-sdk Rust: docs, examples, changelog). Stacked on #159 → #157 → #155; merge those first.

Examples that compile

rust/hey-sdk/examples/ holds five whole programs, each the README's snippet grown into something runnable, and make rs-check now builds them (make rs-examples), so a public-API change that breaks a snippet fails the gate:

  • first_call.rs — identity and boxes from HEY_TOKEN.
  • pagination.rs — a paginated read walked page by page with next_page, then to the end with each_page, with the total count.
  • hooks.rs — a Hooks impl hearing every operation, request and resend.
  • oauth_pkce.rs — the whole PKCE login: loopback listener for the redirect, authorization_url with install_id, state check, code exchange, then a call through a TokenProvider that refreshes on 401.
  • custom_http_client.rs — a transport of the caller's own that answers from a table; runs offline and with --no-default-features, which is what the HttpClient seam exists for.

The four that talk to HEY are required-features = ["reqwest"], so --no-default-features builds only the one that should.

Docs

  • Root README.md gets a Rust section with the same headings as the Go walkthrough — install, authenticate, use it, linked accounts, errors, pagination — plus what the crate has that the module does not. Install stays the git form at a release tag until the crate is on crates.io; the publishing PR switches it.
  • Crate README.md links the examples, gains a Versioning section (pre-1.0 semver as Cargo reads it and as api-compat-rust checks it; MSRV 1.88, when it moves and what that costs; the pinned stable), and describes make rs-check as it now is. The API-governance card may extend that section with the request-construction policy; this is the floor.
  • AGENTS.md and CONTRIBUTING.md describe the gate and the tools.
  • #![cfg_attr(docsrs, feature(doc_cfg))] and doc(cfg(feature = "reqwest")) on ReqwestClient, Client::new and OAuthClient::default, so docs.rs badges them. Verified on nightly locally with --cfg docsrs -D warnings: the badge renders.

Devex

  • rust/rustfmt.toml: stable options only (edition/style_edition 2024, max_width = 100, the two shorthands); it changes nothing in the tree today. imports_granularity/group_imports stay out: they need nightly.
  • make -C rust help and make help list every rs-* target; rs-check is documented as the exact CI step list.
  • .editorconfig gets [*.rs] indent_size = 4.
  • rust-toolchain.toml landed with #155.

Not in this PR

  • CHANGELOG.md / MIGRATING.md: GitHub Releases with .github/release.yml categories are this repo's changelog, and there is no real migration to write yet (the governance card's #[non_exhaustive] change will be the first). No placeholder.
  • crates.io / docs.rs install lines and links — the publishing PR.

Verified locally: make rs-check rs-check-drift green (the whole step list, including the examples); cargo run --example custom_http_client --no-default-features prints the canned boxes.

Merge order

This PR is part of a five-PR stack, each rebased on the one below and all five on current main, so they merge cleanly in this order and only this order: #155 (build/MSRV/feature matrix) → #157 (cargo deny, Dependabot, Trivy) → #159 (semver-checks, packaging) → #160 (docs, examples, rustfmt) → #162 (crates.io publishing). Every one of them touches .github/workflows/test.yml and/or the Makefiles; the stacking is the conflict resolution. Merge each one after the one below has landed; GitHub retargets the next PR to main when the merged branch is deleted. #162 can merge before the crates.io bootstrap: it publishes nothing until the crate exists on crates.io (its publish job fails closed with instructions on a tag until then), and nothing in it changes after the bootstrap.