Add engineering reference documentation - #31
Merged
Conversation
Drop's design detail lived in the README, AGENTS.md, and pull request descriptions, so the reasoning behind the current shape was spread across places that are hard to search and easy to lose. This adds a docs/ directory holding the durable contracts and the working plans: - protocol.md documents the HTTP and WebSocket contract as implemented, including the status strings, control messages, and limits a third client would need to interoperate; - security.md states the trust boundaries, the hostile-input rules, and the weaknesses that are known and accepted, including the ~24-bit session code; - decisions.md records the seven choices that are costly to reverse, so they are not re-litigated; - implementation-checklist.md is the tactical status view; - plans/ holds a full plan per work item, with the rule that a plan is never compressed to a summary, so work can resume with no chat history; - release-checklist.md is the evidence gate for tagging; - validation/ holds a repeatable transfer shakeout recipe; - commands.md indexes the commands, including the workspace-wide invocations that a root-package-only run would miss. Three plans are recorded as proposed: the relay teardown reset deferred out of #30, a receiver preview and confirmation step, and end-to-end encryption. The encryption plan is blocked on a product decision, because it would replace a stated invariant in AGENTS.md. Documentation only; no behavior changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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.
What
Adds a
docs/directory holding Drop's durable contracts and its working plans. Documentation only — no behavior changes.docs/protocol.mddocs/security.mddocs/decisions.mddocs/implementation-checklist.mddocs/plans/docs/release-checklist.mddocs/validation/docs/commands.mdWhy
The reasoning behind the current shape lived in the README,
AGENTS.md, and PR descriptions. The teardown defect is the clearest example: it was diagnosed in #30, written into that PR's description as a follow-up, and had no other home.The plan contract is the load-bearing rule — a plan is saved in full, never compressed to a summary, so phases, risks, validation steps, and open questions survive for whoever picks the work up next.
Plans recorded
All three are proposed; no implementation work has started.
Connection reset by peera sender sees after a successful transfer, deferred out of Stop the CLI transfer tests failing on relay teardown resets #30. The plan records the verified mechanism: the upload receive task breaks onCompleteand dropsws_receiver, so the peer's closing handshake reply lands in a socket nobody reads, and the socket is dropped with data queued — RST instead of FIN. It also records why the obvious fix does not work: the send task owns the sink, not the stream, so the drain has to live in the receive task.AGENTS.mdinvariant forbidding an end-to-end-encrypted claim.Suggested order and its one cost are in
docs/plans/README.md.Notes
security.mddocuments the session code as roughly 24 bits (six hex characters from a UUIDv4) and states honestly what does and does not bound an attacker guessing it.docs/README.mdtracks one known inconsistency:MAX_UPLOAD_SIZE_LABELreads4 GBwhile the enforced limit is 4 GiB.AGENTS.mdgains a Documentation section pointing at the plan contract.Verification
scripts/check-secrets.shpasses.git diff --checkclean.docs/resolves to an existing file.No code changed, so the Rust and web checks are unaffected.
🤖 Generated with Claude Code