Repository navigation
Improve Codebase :: Contract Drift #1386
Description
I have started on this path with #1382 but I thought it would be worth creating an issue to track all of the changes I'm thinking about that will come after this. This audit was done with the help of Claude.
B1. configuration.md — six defaults are wrong or incomplete
| Option | Documented | Actual | Reference |
|---|---|---|---|
listen_on / port |
0.0.0.0:8080 / 8080 |
443 when https_domain is set |
app_config.rs:426-436 |
database_url |
sqlite://sqlpage.db?mode=rwc |
path is relative to the configuration directory; falls back to in-memory if that is not writable; a legacy ./sqlpage.db wins if present |
app_config.rs:630-673 |
max_database_pool_connections |
4 backends listed | 5 branches — ODBC is 50 and in-memory SQLite is 128, neither documented | connect.rs:82-95 |
https_certificate_cache_dir |
./sqlpage/https |
derived from the process working directory, not from the configured web_root or configuration directory |
app_config.rs:711-713 |
max_recursion_depth |
"Maximum value is 255" | not a cap — the u8 type makes 256 a startup failure |
app_config.rs:405-406 |
Also drifted inside the code. The Rust doc comment at app_config.rs:290 says the default upload limit is 10 MiB. The actual default at :703-705 is 5 MiB, and configuration.md correctly says 5 MiB.
Suggested fix. Correct the rows. Then, optionally, add a test that parses the (stable, three-column) table and asserts that documented option names match the struct's serde names and that documented defaults match the values produced by deserialising {}.
B2. sqlpage.request_body() returns '' where the documentation says NULL
What happens. examples/official-site/sqlpage/migrations/55_request_body.sql:65 says the function "returns NULL if there is no request body". On a request with no body SQLPage actually returns an empty string.
B3. fetch_with_meta emits a json_body key that its documentation does not mention
What happens. sqlpage.fetch_with_meta returns the response body under the key body for text responses and under json_body for JSON responses. The documentation
(examples/official-site/sqlpage/migrations/58_fetch_with_meta.sql:14-23) documents a single body key holding "a string, or a json object, depending on the content type".
Activity
81reap commentedon Aug 18, 2026
B1 :: #1391
B2 :: #1392
B3 :: #1393
lovasoa commentedon Aug 18, 2026
Hi ! I'm not a huge fan of AI-generated issue descriptions. AI often has poor judgement about what constitutes an actual issue, its severity, and so on. I do really appreciate your enthusiasm in improving sqlpage, though.
In the future, I would appreciate if you could open separate issues for separate problems, focus on issues that you actually encountered and reproduced yourself (because it helps applying good judgement), and write issue and pull request descriptions yourself. AI-generated (but human reviewed) code is ok !
81reap commentedon Aug 18, 2026
hey! @lovasoa I'll be better about that but many of these issues I'm running into while trying to speed up and fix the CI as well as ask for undocumented features in the code base. I work on NixOS so I have to use a custom flake.nix to be able to run the ci locally and that leads to a lot of small edge cases that unravel into repeated issues across the codebase. I rely on LLMs to force multiply findings
I see that you close the issue out. is there still interest in #1391 and #1393? we can close those out as not-merged if yor not interested in these changes
lovasoa commentedon Aug 20, 2026
Yes, still interested, I left comments on both :)