Skip to content

refactor(types): spike nutype for id newtypes - #10060

Closed
404Wolf wants to merge 2 commits into
mainfrom
wolf/reorg-nutype-spike
Closed

404Wolf wants to merge 2 commits into
mainfrom
wolf/reorg-nutype-spike

Conversation

@404Wolf

@404Wolf 404Wolf commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Why

The reorganization plan adds a crate per entity id (document_id,
channel_id, …) and replaces four hand-rolled id macros. Before writing a
dozen of them, this checks on one real id whether nutype (already a
workspace dependency) can replace the hand-written trait impls without
changing anything on the wire: Postgres encoding, OpenAPI schema, and serde.
harness_id is the test subject because it has every impl by hand.

MACRO-4999

How it works

The first commit pins today's behaviour in tests, run green against the
hand-written impls:

  • serde: a JSON string of the UUID (this test already existed).
  • OpenAPI: the schema is named HarnessId and serializes to exactly
    {"type":"string"}.
  • Postgres: type_info, compatible and the array type equal Uuid's, and
    the encoded bytes equal the UUID's 16 bytes.

The second commit rewrites HarnessId as a #[nutype] with const_fn and
derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Display, Serialize, Deserialize), plus derive_unchecked(sqlx::Type) with
#[sqlx(transparent)] behind the sqlx feature. The public API
(new_from_uuid, as_uuid, parse_uuid_str, TEST_A/TEST_B, the
FromStr error) is unchanged. All 6 tests pass.

Findings

  • sqlx: works. nutype forwards #[sqlx(transparent)] to the
    derive_unchecked(sqlx::Type) derive, which replaces the four hand-written
    impls (Type, PgHasArrayType, Encode, Decode). The harnesses,
    macro_authorization and bots DB tests round-trip HarnessId through
    real Postgres queries and pass.
  • serde: works. nutype's own Serialize/Deserialize are transparent.
  • utoipa: keep it hand-written for ids that were hand-written.
    derive_unchecked(utoipa::ToSchema) copies the doc comment into the schema
    as a description. The new characterization test caught that this would
    change the published OpenAPI. Ids whose schema already comes from
    #[derive(utoipa::ToSchema)] (the database_id!/form_id! macros) carry
    that description today, so for them the derive is a no-op change.
  • FromStr: hand-written when the error type matters. nutype's
    derive(FromStr) wraps the inner type's parse error in a generated enum.
    Ids with their own error type, like HarnessIdParseError, keep a
    three-line impl.
  • specta: not exercised here (harness_id has none). The id macros PR
    checks it on the models_databases and models_forms ids, whose
    generated TypeScript is checked in.

Verdict: use nutype for new id crates. Hand-write ToSchema only where the
current schema has no description, and FromStr only where an id has its own
error type.

Characterizes what the hand-written impls produce so the next commit can
replace them without changing the wire format.
nutype replaces the hand-written Display, serde and sqlx impls; sqlx's
transparent derive is forwarded through derive_unchecked. ToSchema stays
hand-written because the derive would add the doc comment to the
OpenAPI schema as a description. The previous commit's tests pin the
wire format, and pass unchanged.

MACRO-4999
@macro-application

Copy link
Copy Markdown

@404Wolf 404Wolf added the run-ci Run CI on the PR's head commit; removed when the run starts label Nov 7, 2026
@github-actions github-actions Bot added cloud-storage and removed run-ci Run CI on the PR's head commit; removed when the run starts labels Nov 7, 2026
@coderabbitai

coderabbitai Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Note

Some coding-guideline sources were skipped or only partly applied; the reason is listed next to each one. On a public repository, this repository's guideline files are counted without their names.

Skipped guideline sources

225 AGENTS.md files in this repository — not scanned for links to other guideline files; the limit of 50 AGENTS.md files per review was reached
167 guideline files in this repository — not read for this review; the limit of 100 guideline files per review was reached

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Compatibility
    • Harness IDs retain UUID-compatible PostgreSQL type handling and encoding, including array support.
    • The as_uuid accessor is no longer a compile-time constant function; callers can still use it at runtime to retrieve the underlying UUID.

HarnessId now uses nutype for its UUID-backed newtype and derives traits, including feature-gated SQLx type support. Its construction, UUID access, and parsing methods use generated nutype methods. The manual PostgreSQL SQLx implementations were removed. Feature-gated tests check its OpenAPI schema and PostgreSQL type and encoding behavior.

Merge Risk: Minimal · up to 3dfed

No concrete issue remains that would prevent merging after normal checks.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title describes the nutype refactor, follows conventional commits format, and is under 72 characters.
Description check Passed The description covers the HarnessId refactor and characterization tests. However, its claim that the public API is unchanged conflicts with as_uuid no longer being const.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between d7cb768 and 3dfed76.

Files ignored due to path filters: 1

  • Cargo.lock is excluded by !**/*.lock, !**/Cargo.lock
Files selected for processing: 3

  • crates/harness_id/Cargo.toml
  • crates/harness_id/src/lib.rs
  • crates/harness_id/src/test.rs

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 0 remain after this review.

@404Wolf

404Wolf commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Folded into the single reorg PR #10111 (one PR for the whole reorganization). Its commits are there; closing this one.

@404Wolf 404Wolf closed this Nov 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant