Publish groundwork: docs, package metadata, decoder fuzzing - #16
Merged
Conversation
Everything needed before `npm publish` except the publish itself. Docs. packages/hyperfly had no README, so the npm page would have shipped blank; it now covers the two-line usage, plans and profiles, serving over the negotiation protocol, and the benchmark table with its caveats. Python and Rust get equivalent front doors, the root README stops claiming nothing is benchmarked, and the site's dead "docs — soon" button points at the README. Packaging. Verified by building the tarball and installing it into a scratch project as a consumer: all three entry points resolve, encode and decode round trip, training works, and the HTTP layer negotiates — the check that usually catches a broken exports map. prepublishOnly now runs lint, types, tests and a fresh build, so a stale or failing build cannot be published. Added keywords, homepage, bugs, and provenance. Fuzzing. The decoder is the one component that eats bytes from the network, and it had property tests for valid input but nothing for hostile input. The new suite throws roughly thirty-four thousand inputs at it across both plans — random bytes, bit-mutations of valid output, truncation at every offset, arbitrary dictionary codes, hostile envelopes — and requires that every one either raises a typed HyperflyError or normalizes to a stable fixed point. Its first run failed, and the implementation was right: a mutated input decoded to values where delta and raw modes tie on size, so the encoder correctly chose the lower mode byte and re-encoded to different bytes. Plan section 4 makes canonicality an encoder obligation and explicitly lets decoders accept any valid mode, so byte identity only holds for output a conforming encoder produced. The assertion is now the invariant that actually holds — decode, re-encode, and require a fixed point — which still catches a decoder that loses or invents information. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_hf1
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.
Everything needed before
npm publishexcept the publish itself — that's yours.Docs
packages/hyperflyhad no README, so the npm page would have shipped blank. It now covers two-line usage, plans and profiles, serving over the negotiation protocol, and the benchmark table with its caveats intact. Python and Rust get equivalent front doors, the root README stops claiming nothing is benchmarked, and the site's deaddocs — soonbutton now points somewhere.Packaging, verified rather than assumed
Built the tarball and installed it into a scratch project as a real consumer:
All three entry points (
hyperfly,/zod,/http) resolve — the check that usually catches a broken exports map. Tarball is 37 kB and contains README, LICENSE, NOTICE, dist.prepublishOnlynow runs lint + types + tests + a fresh build, so a stale or failing build can't be published. Added keywords, homepage, bugs, provenance.Name status: npm
hyperflyis yours at 0.1.0 (the old load balancer — worth anpm deprecatepointing at the new major), PyPIhyperflyis available.Decoder fuzzing
The decoder eats bytes from the network and had property tests for valid input only. The new suite throws ~34,000 hostile inputs at it across both plans — random bytes, bit-mutations of valid output, truncation at every offset, arbitrary dictionary codes, hostile envelopes — requiring each to either raise a typed
HyperflyErroror normalize to a stable fixed point. NoTypeError, noRangeError, no hang.Its first run failed, and the implementation was right. A mutated input decoded to values where delta and raw modes tie on size, so the encoder correctly picked the lower mode byte and re-encoded differently. Plan §4 makes canonicality an encoder obligation and explicitly lets decoders accept any valid mode — so byte identity only holds for output a conforming encoder produced. The assertion is now the invariant that actually holds, and still catches a decoder that loses or invents information.
TS 200 tests / 10.6k assertions, Python 138, Rust 9.
🤖 Generated with Claude Code