camelCase the reading-progress transfer wire format, and unbreak macOS builds - #46
Merged
Merged
Conversation
Homebrew lld cannot resolve libSystem primitives (bzero, memset, lchown, fchown) against the macOS 27 SDK, so every binary and test link fails with hundreds of undefined symbols. Anyone on a current macOS could not build at all, and the failure reads as a mess of missing libc symbols rather than as a linker mismatch, so it costs an afternoon to trace. Upgrading does not help: the newest published lld has the same problem. Drop the pin for both macOS targets and let Cargo fall back to Apple's ld, which works and is fast enough that the lost link time is not worth a broken build. Linux keeps mold.
The export document, the import request and the import report were the only payloads in the API spelling their fields in snake_case. The reasoning was that the document is a portable interchange file rather than something a frontend deserializes, but it is both: the export returns it as a response body, and the import nests it inside its request. That second point is what settles it, because a camelCase request wrapping a snake_case document puts two naming conventions in one JSON body with no visible boundary between them, and the frontend reads both through the same generated types. Only the structs change. The enums keep snake_case variants, which is how enum values are spelled everywhere else in the API. Nothing has consumed the format yet, so this is free now and a breaking change later.
Deploying codex with
|
| Latest commit: |
5e497fb
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://4a2b8ae7.codex-asm.pages.dev |
| Branch Preview URL: | https://fix-reading-progress-transfe.codex-asm.pages.dev |
API contract changesCompared against Report |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two independent changes. The first is a build fix that anyone on a current macOS needs; the second is the wire-format change discussed on the transfer work. They are separate commits, so the build fix can be cherry-picked if this takes a while to review.
fix(build): use the system linker on macOSHomebrew lld cannot resolve libSystem primitives (
bzero,memset,lchown,fchown) against the macOS 27 SDK, so every binary and test link dies with hundreds of undefined symbols. Upgrading does not help, the newest published lld has the same problem. Dropping the pin lets Cargo fall back to Apple'sld, which works. Linux keeps mold.refactor(api): camelCase the transfer payloadsThe export document, import request and import report were the only payloads in the API spelling their fields in snake_case. The original reasoning was that the document is a portable interchange file rather than something a frontend deserializes.
It is both, and that is what settles it:
GET /reading-progress/exportreturns the document as a response body.POST /reading-progress/importnests the whole document inside its request atfile.So a camelCase request wrapping a snake_case document would put two naming conventions in one JSON body with no visible boundary, and the frontend reads both through the same generated types.
Only the structs change. The enums (
HashMode,ConflictPolicy,SeriesDisposition,BookDisposition,FieldOutcome) keep snake_case variants, matching how enum values are spelled everywhere else in the API. Values likestem_matchandskip_existingare unchanged.The export query parameter goes
include_sessionstoincludeSessions, matchingexternalIdandpluginIdelsewhere.Nothing has consumed the format yet, so this is free now and a breaking change later.
Verification
tsc -bclean, biome clean, clippy cleanNo version bump in this PR, deliberately.