Skip to content

refactor: simplify the creation API and parser errors (#380 part 3b) - #391

Merged
oglassdev merged 6 commits into
mainfrom
cleanup/parser-api-errors
Sep 24, 2026
Merged

oglassdev merged 6 commits into
mainfrom
cleanup/parser-api-errors

Conversation

@oglassdev

Copy link
Copy Markdown
Owner

Part 3b of #380. This simplifies the parser's public creation API and merges its write errors, then derives the parser error impls with thiserror. Databases produced by the library are byte-identical, and every error message is unchanged.

Creation API

Before: seven public functions:

  • create_database
  • create_database_with_rows
  • create_database_with_table_rows
  • create_database_with_relationship
  • create_database_with_relationship_rows
  • create_database_with_relationships
  • create_database_with_relationships_and_rows

After: one function, create_database(path, &DatabaseSpec, budget) -> Result<(), WriteError>.

pub struct DatabaseSpec<'a> {
    pub tables: &'a [TableRows<'a>],               // schema + initial rows, in order
    pub relationships: &'a [RelationshipSpec<'a>],
    pub relationship_layout: RelationshipLayout,    // Graph (default) | SingleLong
}

Migration:

// before
create_database(path, &[people], &mut budget)?;
create_database_with_rows(path, &people, &rows, &mut budget)?;
create_database_with_relationships_and_rows(path, &requests, &relationships, &mut budget)?;
create_database_with_relationship(path, &[parent, child], &relationship, &mut budget)?;

// after
create_database(path, &DatabaseSpec { tables: &[TableRows::empty(people)], ..DatabaseSpec::default() }, &mut budget)?;
create_database(path, &DatabaseSpec { tables: &[TableRows { table: people, rows: &rows }], ..DatabaseSpec::default() }, &mut budget)?;
create_database(path, &DatabaseSpec { tables: &requests, relationships: &relationships, ..DatabaseSpec::default() }, &mut budget)?;
create_database(path, &DatabaseSpec {
    tables: &[TableRows::empty(parent), TableRows::empty(child)],
    relationships: std::slice::from_ref(&relationship),
    relationship_layout: RelationshipLayout::SingleLong,
}, &mut budget)?;

Inside create_database, requests still go to the same composer and checks as before:

  • With no relationships and no rows, it uses the old schema-only path.
  • With no relationships and rows, it uses the old table-rows path.
  • Graph relationships use the graph path.
  • SingleLong uses the single-relationship path, with or without rows.

TableRows::empty is a new convenience constructor. The CLI now picks the layout from its relationships or relationship JSON field and makes a single call.

Two edge cases now behave differently:

  • A table passed with an empty row list used to go through the rows path. It now takes the schema-only path, which accepts a schema with two AutoIncrement columns.
  • A SingleLong request with no rows used to refuse a parent table with a second index. It now succeeds.

Two tests that relied on the old refusals were changed to supply one row so they still exercise the rows-path refusal.

Single-relationship path: kept, because its bytes differ

Before deleting anything, I checked whether the graph path could replace the single-relationship path. A temporary probe (not committed) composed every single-relationship request twice, once through the single path and once through the graph path, and compared the bytes. It covered every such request in the golden corpus and the create:: tests. None of the successful cases matched.

  • Page 0, offset 1538: the single path writes the EXP-0114 page-zero transition byte (0x02). The graph path writes the creation counter there (0x04 for two tables). This affects every case.
  • With rows: one table-definition byte also differs. It sits in a physical-index prefix at offset 43 or 51 of the child table definition. The single path writes 0; the graph path writes the key or row count (0x14, 0xc8, 0xc9, 0x04 and 0x01 were seen).
  • Accepted inputs differ too. The single path refuses one-to-one, cascades and join types, a child with more than one ascending Long primary index, and (with rows) a parent that has more than one index. The graph path accepts all of these.

Following the brief, I did not delete the path. It is now internal (pub(super)) and reached through RelationshipLayout::SingleLong, whose doc comment explains how its bytes differ. Its tests are unchanged.

Errors

Before: 42 public *Error types (49 including crate-private ones), about 135 hand-written Display/Error/From impls and conversion! lines.

  • UpdateError (26 variants) and CreateDatabaseError (2 variants) were separate public types.
  • ImageCheckError was declared pub inside a private module.
  • There was a lossy public From<UpdateError> for ColumnPropertyError.

After: 40 public (48 in total), with 8 hand-written impls left.

  • WriteError (write/error.rs) is the single error for insert, update, delete, schema edits and create_database.
    • The former UpdateError variants keep their names, so their field update failed: {self:?} text is identical.
    • Creation adds two variants: Compose(ComposeError), which prints "database composition failed: …", and CreatePublish(PublishError), which prints "database publication failed: …".
  • ImageCheckError is now pub(crate) in create/check.rs. The creation-time candidate checks have moved there as well.
  • The lossy From is replaced by a crate-private ColumnPropertyError::from_ownership_check, used at its one call site. ColumnPropertyError stays as the property reader's error.
  • Other low-level decoder, encoder and validator errors keep their own types. I did not add a ReadError umbrella.
  • ComposeError::Properties now boxes its payload, which keeps WriteError under clippy's result_large_err limit. Box's Debug output is transparent, so the message text is unchanged.

thiserror 2.0.21 derives Display, Error, source and From for the remaining parser errors. Debug-based messages use an enum-level #[error("…{self:?}")]. Some impls stay hand-written:

  • ValidationError and PublishError keep a hand-written Display, because their text depends on runtime data.
  • A few From impls stay manual: some map one source error onto several variants, and in others #[from] would have changed what source() returns.

cargo deny check passes: advisories, bans, licenses and sources are all ok. CLI and testkit errors were not converted.

Also

row/insert_page.rs: minimum_row now returns Unsupported("row column count") when a layout has more than 255 columns. It used to fall back silently to a full set of nulls. A focused test covers this.

Checks

  • Golden: scripts/golden-check.sh 9ee8a73 reports 1923 files, all identical, after every commit.
  • Error text: removed and added message literals were also compared directly. The only difference is one test-only message whose constant is now passed as a format argument; the rendered text is the same.
  • Tests: cargo test -p jet3 gives 825 passed + 6 ignored in the lib (was 823 + 6), 17 integration and 2 doc tests (unchanged). The two new tests are the WriteError message prefixes and minimum_row. No tests were removed or merged.
  • cargo check -p jet3 --all-targets --target x86_64-pc-windows-gnu is clean.
  • just ready passes.

Line counts

Production code in crates/jet3/src (excluding *_tests.rs, tests.rs and testkit.rs) went from 41,849 lines to 40,692.

Not touched: oracle/windows-dao/protocol/v1_2/README.md still names the old create_database_with_* functions. It is outside this PR's scope because an oracle PR is in flight.

🤖 Generated with Claude Code

Replace the seven create_database* functions with
create_database(path, &DatabaseSpec, budget). DatabaseSpec holds the
tables with their initial rows, the relationships, and a
RelationshipLayout choosing between the relationship-graph layout
(default) and the EXP-0118/0122 single Long relationship layout, whose
bytes differ from the graph layout for the same request.

Candidate image checks move to create/check.rs.
UpdateError and CreateDatabaseError become one public WriteError in
write/error.rs, returned by insert, update, delete, schema edits and
create_database. Creation failures keep their messages through the
Compose and CreatePublish variants. The candidate image check error is
crate-private, and the lossy From<UpdateError> for ColumnPropertyError is
replaced by an explicit crate-private mapping at its one call site.
Replace hand-written Display, Error, source and From impls with
thiserror derives. Messages are unchanged; Debug-based messages use an
enum-level #[error("...{self:?}")]. ValidationError and PublishError
keep hand-written Display because their text branches on runtime data;
a few From impls that map between variants stay manual.
minimum_row fell back to a full null set when a layout had more than
255 columns. Return Unsupported("row column count") instead.
@oglassdev
oglassdev merged commit f2f4396 into main Sep 24, 2026
10 checks passed
@oglassdev
oglassdev deleted the cleanup/parser-api-errors branch September 24, 2026 20:20
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